source: palm/tags/release-3.9/TUTORIAL/SOURCE/user_defined_code.tex @ 3901

Last change on this file since 3901 was 973, checked in by maronga, 12 years ago

tutorial updates

  • Property svn:keywords set to Id
File size: 30.5 KB
Line 
1% $Id: user_defined_code.tex 973 2012-08-07 16:03:47Z suehring $
2\input{header_tmp.tex}
3%\input{../header_lectures.tex}
4
5\usepackage[utf8]{inputenc}
6\usepackage{ngerman}
7\usepackage{pgf}
8\usetheme{Dresden}
9\usepackage{subfigure}
10\usepackage{units}
11\usepackage{multimedia}
12\usepackage{hyperref}
13\newcommand{\event}[1]{\newcommand{\eventname}{#1}}
14\usepackage{xmpmulti}
15\usepackage{tikz}
16\usetikzlibrary{shapes,arrows,positioning}
17\usetikzlibrary{decorations.markings}             %neues paket
18\usetikzlibrary{decorations.pathreplacing}        %neues paket
19\def\Tiny{\fontsize{4pt}{4pt}\selectfont}
20\usepackage{amsmath}
21\usepackage{amssymb}
22\usepackage{multicol}
23\usepackage{pdfcomment}
24\usepackage{graphicx}
25\usepackage{listings}
26\lstset{showspaces=false,language=fortran,basicstyle=
27        \ttfamily,showstringspaces=false,captionpos=b}
28
29\institute{Institut fÌr Meteorologie und Klimatologie, Leibniz UniversitÀt Hannover}
30\date{last update: \today}
31\event{PALM Seminar}
32\setbeamertemplate{navigation symbols}{}
33
34\setbeamertemplate{footline}
35  {
36    \begin{beamercolorbox}[rightskip=-0.1cm]&
37     {\includegraphics[height=0.65cm]{imuk_logo.pdf}\hfill \includegraphics[height=0.65cm]{luh_logo.pdf}}
38    \end{beamercolorbox}
39    \begin{beamercolorbox}[ht=2.5ex,dp=1.125ex,
40      leftskip=.3cm,rightskip=0.3cm plus1fil]{title in head/foot}
41      {\leavevmode{\usebeamerfont{author in head/foot}\insertshortauthor} \hfill \eventname \hfill \insertframenumber \; / \inserttotalframenumber}
42    \end{beamercolorbox}
43    \begin{beamercolorbox}[colsep=1.5pt]{lower separation line foot}
44    \end{beamercolorbox}
45  }
46%\logo{\includegraphics[width=0.3\textwidth]{luhimuk_logo.pdf}}
47
48\title[The PALM User-Interface]{The PALM User-Interface}
49\author{Siegfried Raasch}
50
51\begin{document}
52
53% Folie 1
54\begin{frame}
55\titlepage
56\end{frame}
57
58\section{The PALM User-Interface}
59\subsection{The PALM User-Interface}
60
61% Folie 2
62\begin{frame}
63   \frametitle{Purpose of the User-Interface}
64   \scriptsize
65   \begin{itemize}
66      \item<2-> The standard (default) PALM code cannot account for every specific demand of a user. In order to include these specific demands, the user would have to modify the standard code.
67   \end{itemize}
68   \vspace{2mm}
69   \onslide<3->
70   \textbf{Problem:}
71   \begin{itemize}
72      \item<3-> If a new PALM version is released (current release is 3.8) and the user wants to use it, he would have to add his modifications to the new release again.
73   \end{itemize}   
74   \vspace{3mm}
75   \onslide<4->
76   \textbf{Solution:}
77   \begin{itemize}
78      \item<4-> PALM offers a \grqq user-interface\grqq, i.e. a set of subroutines, where the user can add his modifications and which can be re-used for future releases of the standard PALM code.
79      \item<5-> By using the user-interface, the standard code does not have to be modified by the user in most of all cases.
80      \item<6-> The user-interface subroutines are almost \grqq empty\grqq\, by default. They are called from the standard PALM code but (with some very minor exceptions) do not contain any executable code.
81   \end{itemize}   
82\end{frame}
83
84% Folie 3
85\begin{frame}
86   \frametitle{General Structure of the User-Interface}
87   \scriptsize
88   \begin{itemize}
89      \item<1-> All routines can be found under \texttt{.../trunk/SOURCE}.
90      \item<2-> There is one file for each routine. Filenames are \texttt{user\underline{ }*.f90}.\\
91Example: \texttt{user\underline{ }last\underline{ }actions.f90}
92   \end{itemize}
93   \onslide<3->
94   \centering
95   \includegraphics[scale=0.3]{user_defined_code_figures/user_last_actions.png}\\   
96\end{frame}
97
98% Folie 4
99\begin{frame}
100   \frametitle{Embedding of User-Interface Routines}
101   \scriptsize
102   \begin{itemize}
103      \item<1-> The user-interface routines are called from specific, well-defined locations in the standard PALM code.\\
104   \ \\
105   Example from \texttt{palm.f90}:
106   \end{itemize}
107   \onslide<2->
108   \centering
109   \includegraphics[scale=0.33]{user_defined_code_figures/embedding.png}\\
110\end{frame}
111
112
113% Folie 5
114\begin{frame}
115   \frametitle{Embedding of User-Interface Routines\\
116   Flow Chart Overview (I): Initial Steps}
117   \scriptsize
118   \begin{tikzpicture}[scale=0.8, transform shape]
119      % Define colours
120      \tikzstyle{green} = [draw, fill=green!30, text width=7.1em, text centered, minimum height=1.6em]
121      \tikzstyle{yellow} = [draw, fill=yellow!30, text width=7.1em, text centered, minimum height=1.6em]
122      \tikzstyle{orange} = [draw, fill=orange!60, text width=7.1em, text centered]
123     
124      % Define coordinates and draw nodes     
125      \node[green, text width=5em] (PALM) at (0,0.1) {PALM};
126
127      \coordinate (A) at (0,-0.7);
128
129      \node[green, right=0.6cm of A] (parin) {parin};
130     
131      \coordinate[below=0.3cm of parin] (B);
132      \coordinate[below=0.9cm of parin] (C);
133      \coordinate[below=1.5cm of parin] (D);
134     
135      \node[green, right=0.6cm of B] (read) {read\_var\_list};
136      \node[green, right=0.6cm of C] (package) {package\_parin};
137      \node[yellow, right=0.6cm of D] (userparin) {user\_parin};
138     
139      \coordinate[below=3cm of PALM] (E);     
140      \coordinate[below=3.6cm of PALM] (F);   
141      \coordinate[below=4.2cm of PALM] (G);     
142      \coordinate[below=4.8cm of PALM] (H);
143      \coordinate[below=5.6cm of PALM] (I);
144      \coordinate[below=7.4cm of PALM] (J);             
145               
146      \node[green, right=0.6cm of E] (initpegrid) {init\_pegrid};     
147      \node[green, right=0.6cm of F] (initgrid) {init\_grid};
148      \node[yellow, right=0.9cm of initgrid] (userinitgrid) {user\_init\_grid};
149     
150      \node[green, right=0.6cm of G] (checkparameters) {check\_parameters};       
151      \node[yellow, right=0.9cm of checkparameters, text width=9.5em] (usercheckdataoutput) {user\_check\_data\_output};
152      \node[green, right=0.6cm of H] (header) {header};
153      \node[green, right=0.6cm of I] (init3dmodel) {init\_3d\_model};       
154      \node[yellow, right=0.9cm of header] (userheader) {user\_header};
155           
156      \node[orange, right=0.6cm of J] (timeint) {time\_integration};       
157     
158      \coordinate[below=0.3cm of init3dmodel] (K);   
159      \coordinate[below=0.9cm of init3dmodel] (L);       
160     
161      \node[green, right=0.6cm of K] (initparticles) {init\_particles};       
162      \node[yellow, right=0.9cm of initparticles] (userinitparticles) {user\_init\_particles};   
163      \node[yellow, right=0.6cm of L] (userinit) {user\_init};       
164     
165      % Draw lines
166      \draw[-, thick] (PALM) -- (0,-7.8);
167      \draw[dotted, thick] (0,-8.2) -- (0,-7.8);
168      \draw[-, thick] (A) -- (parin);
169      \draw[-, thick] (parin) -- (D); 
170      \draw[dashed, thick] (B) -- (read);
171      \draw[dashed, thick] (C) -- (package);
172      \draw[-, thick] (D) -- (userparin);
173      \draw[-, thick] (E) -- (initpegrid);
174      \draw[-, thick] (F) -- (initgrid);
175      \draw[-, thick] (G) -- (checkparameters);
176      \draw[-, thick] (H) -- (header);
177      \draw[-, thick] (I) -- (init3dmodel);
178      \draw[-, thick] (J) -- (timeint);
179      \draw[dotted, thick] (init3dmodel) -- (K);
180      \draw[-, thick] (K) -- (L);
181      \draw[dashed, thick] (K) -- (initparticles);
182      \draw[-, thick] (L) -- (userinit);
183      \draw[-, thick] (initgrid) -- (userinitgrid);     
184      \draw[-, thick] (checkparameters) -- (usercheckdataoutput);     
185      \draw[-, thick] (header) -- (userheader);     
186      \draw[-, thick] (initparticles) -- (userinitparticles);     
187     
188   \end{tikzpicture}
189\end{frame}
190
191% Folie 6
192\begin{frame}
193   \frametitle{Embedding of User-Interface Routines\\
194   Flow Chart Overview (II): Time Integration Loop}
195   \scriptsize
196   \begin{tikzpicture}[scale=0.7, transform shape]
197      % Define colours
198      \tikzstyle{green} = [draw, fill=green!30, text width=7.1em, text centered, minimum height=1.6em]
199      \tikzstyle{yellow} = [draw, fill=yellow!30, text width=7.1em, text centered, minimum height=1.6em]
200      \tikzstyle{orange} = [draw, fill=orange!60, text width=7.1em, text centered]
201      \tikzstyle{orange1} = [draw, fill=orange!80, text width=11em, text centered]     
202      \definecolor{grey}{rgb}{0.25,0.25,0.25}
203
204      % Define coordinates and draw nodes     
205      \node[draw, text width=25em,minimum height=4.0em,fill=black!15] (progframe) at (5.75,-1.5) {};
206
207      \coordinate (A) at (0,0);
208
209      \node[orange, right=0.6cm of A] (timeint) {time\_integration};       
210     
211      \coordinate[below=0.3cm of timeint] (B);
212      \coordinate[below=0.8cm of timeint] (C);   
213      \coordinate[right=2cm of C] (D);   
214      \coordinate[right=3.8cm of D] (E);
215                 
216      \node[yellow, right=0.6cm of B, text width=14em] (useractions1) {\textcolor{blue}{user\_actions\_(\textit{'before\_timestep'})}};   
217         
218      \node[orange1, below=0.2cm of D] (progeq) {prognostic\_equations};   
219      \node[orange1, below=0.2cm of E] (progeqfast) {prognostic\_equations\_fast};
220      \node[draw, fill=red, text width=4em] at (8.6,-0.8) {\textcolor{white}{standard advection}};
221               
222      \node[yellow, right=0.3cm of progframe, text width=14em] (useractions2) {\textcolor{blue}{user\_actions\_(\textit{'*\_tendency'})}};
223     
224     
225      \coordinate[below=2.3cm of timeint] (F);
226      \coordinate[below=2.9cm of timeint] (G);
227      \coordinate[below=3.5cm of timeint] (H);
228      \coordinate[below=4.1cm of timeint] (I);
229
230                             
231      \node[green, right=0.6cm of F] (advecparticles) {advec\_particles};
232      \node[yellow, right=0.9cm of advecparticles, text width=10em] (userparticlesattributes) {user\_particles\_attributes};
233      \node[green, right=0.6cm of G] (exchangehoriz) {exchange\_horiz}
234      \node[green, right=0.0cm of exchangehoriz] (asselin) {asselin\_filter};     
235      \node[green, right=0.6cm of H] (swaptimelevel) {swap\_timelevel};
236      \node[green, right=0.6cm of I] (pres) {pres};
237     
238      \coordinate[below=0.3cm of pres] (J);   
239      \coordinate[below=5.1cm of timeint] (K);     
240      \coordinate[below=5.7cm of timeint] (L);
241      \coordinate[below=6.3cm of timeint] (M);
242      \coordinate[below=6.9cm of timeint] (N);     
243      \coordinate[below=8.2cm of timeint] (O);
244      \coordinate[below=8.8cm of timeint] (P);     
245                 
246      \node[green, right=0.6cm of K] (prandtlfluxes) {prandtl\_fluxes};   
247      \node[yellow, right=0.6cm of L, text width=14em] (useractions3) {\textcolor{blue}{user\_actions\_(\textit{'after\_integration'})}};             
248      \node[green, right=0.6cm of M] (diffusivities) {diffusivities};             
249      \node[green, right=0.0cm of diffusivities] {check\_for\_restart};     
250      \node[green, right=0.6cm of N] (flowstat) {flow\_statistics};
251      \node[green, right=0.0cm of flowstat] (runcontrol) {run\_control}
252      \node[yellow, below=0.2cm of flowstat] (userstat) {user\_statistics}
253      \node[yellow, right=0.6cm of O, text width=14em] (useractions4) {\textcolor{blue}{user\_actions\_(\textit{'after\_timestep'})}};
254      \node[green, right=0.6cm of P] (timestep) {timestep};             
255
256      \node[green, right=0.2cm of runcontrol] (dataoutput) {data\_output\_***};
257      \node[yellow, right=0.2cm of dataoutput] (userdvrpcoltab) {user\_dvrp\_coltab};
258      \coordinate[below=0.2cm of dataoutput] (Q);   
259      \coordinate[right=0.4cm of Q] (R);   
260      \coordinate[right=3.0cm of R] (S);
261         
262      \node[yellow, below=0.2cm of R, text width=9em] (output2d) {user\_data\_output\_2d};
263      \node[yellow, below=0.2cm of S, text width=9em] (output3d) {user\_data\_output\_3d};
264     
265
266
267      \draw[dotted, thick] (0,0.05) -- (0,0.3);
268      \draw[-, thick] (0,0.05) -- (0,-8.8);
269      \draw[dotted, thick] (0,-9.2) -- (0,-8.8);
270      \draw[-, thick] (A) -- (timeint);
271      \draw[-, thick] (timeint) -- (P);
272      \draw[-, thick] (B) -- (useractions1);
273      \draw[-, thick] (C) -- (D);
274      \draw[-, thick] (progeq) -- (D);     
275      \draw[-, thick, color=red] (D) -- (E);
276      \draw[->, thick, color=red] (E) -- (progeqfast);       
277      \draw[-, thick] (progframe) -- (useractions2);
278      \draw[-, thick] (F) -- (advecparticles);   
279      \draw[-, thick] (userparticlesattributes) -- (advecparticles);   
280      \draw[-, thick] (G) -- (exchangehoriz);
281      \draw[-, thick] (H) -- (swaptimelevel);
282      \draw[-, thick] (I) -- (pres);     
283      \draw[dotted, thick] (pres) -- (J);
284      \draw[-, thick] (K) -- (prandtlfluxes);   
285      \draw[-, thick] (L) -- (useractions3);     
286      \draw[-, thick] (M) -- (diffusivities); 
287      \draw[-, thick] (N) -- (flowstat); 
288      \draw[-, thick] (userstat) -- (flowstat); 
289      \draw[-, thick] (O) -- (useractions4);
290      \draw[-, thick] (P) -- (timestep);   
291      \draw[-, thick] (dataoutput) -- (Q);
292      \draw[-, thick] (S) -- (Q);
293      \draw[-, thick] (R) -- (output2d);
294      \draw[-, thick] (S) -- (output3d);
295   \end{tikzpicture}
296\end{frame}
297
298
299% Folie 7
300\begin{frame}
301   \frametitle{Embedding of User-Interface Routines\\
302   Flow Chart Overview (III): Final Steps}
303   \scriptsize
304   \begin{tikzpicture}[scale=0.8, transform shape]
305      % Define colours
306      \tikzstyle{green} = [draw, fill=green!30, text width=7.1em, text centered, minimum height=1.6em]
307      \tikzstyle{yellow} = [draw, fill=yellow!30, text width=7.1em, text centered, minimum height=1.6em]
308      \tikzstyle{orange} = [draw, fill=orange!60, text width=7.1em, text centered]
309     
310      % Define coordinates and draw nodes     
311      \node[green, text width=5em] (PALM) at (0,0.1) {PALM};
312
313      \coordinate (A) at (0,-0.7);
314
315
316      \node[orange, right=0.6cm of A] (timeint) {time\_integration};       
317      \coordinate[below=0.5cm of timeint] (B);
318      \coordinate[below=1.0cm of timeint] (C);   
319     
320      \coordinate[below=2.5cm of PALM] (D); 
321     
322      \node[green, right=0.6cm of D] (write3dbinary) {write\_3d\_binary};
323      \node[green, right=0.9cm of write3dbinary] (writevarlist) {write\_var\_list};   
324       
325      \coordinate[below=3.5cm of PALM] (E);
326      \coordinate[below=4.1cm of PALM] (F);
327      \coordinate[below=4.7cm of PALM] (G);
328      \node[green, right=0.6cm of E] (header) {header};     
329      \node[yellow, right=0.6cm of F] (userlastactions) {user\_last\_actions};   
330      \node[green, right=0.6cm of G] (cpustat) {cpu\_statistics};               
331      % Draw lines
332      \draw[-, thick] (PALM) -- (G);
333      \draw[-, thick] (A) -- (timeint);
334      \draw[-, thick] (B) -- (timeint);
335      \draw[dotted, thick] (B) -- (C);
336      \draw[dashed, thick] (D) -- (write3dbinary);
337      \draw[-, thick] (write3dbinary) -- (writevarlist);
338      \draw[-, thick] (E) -- (header);
339      \draw[-, thick] (F) -- (userlastactions);
340      \draw[-, thick] (G) -- (cpustat);
341
342   \end{tikzpicture}
343\end{frame}
344
345% Folie 8
346\begin{frame}
347   \frametitle{Complete List of User-Interface Routines (I)}
348   \tiny
349   \begin{tabular}{|p{2.5cm}|p{2.4cm}|p{2.1cm}|p{3cm}|}
350      \hline
351           \textbf{Name} & \textbf{Arguments} & \textbf{Called from} & \textbf{Task}\\
352           \hline
353           \texttt{user\_3d\_data\_averaging} & \texttt{mode}, \texttt{variable} & \texttt{sum\_up\_3d\_data} & temporal averaging for user-defined quantities\\
354           \hline
355           \texttt{user\_actions} \texttt{user\_actions} & \texttt{location} \,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\, \texttt{i}, \texttt{j}, \texttt{location} & \texttt{time\_integration} +
356\texttt{prognostic\_equations} & e.g. additional forces to be included in the prognostic equations\\
357           \hline
358           \texttt{user\_dummy (user\_additional \_routines.f90)} & - - - & - - - & for additional subroutines defined by the user\\
359           \hline
360           \texttt{user\_advec\_particles} & - - - & \texttt{advec\_particles} & modification of particles after advection\\
361           \hline
362           \texttt{user\_check\_data\_output} & \texttt{variable}, \texttt{unit} & \texttt{check\_parameters} & check the user-defined output quantities\\
363           \hline
364           \texttt{user\_check\_data\_output\_pr} & \texttt{variable}, \texttt{var\_count}, \texttt{unit} & \texttt{check\_parameters} & check the user-defined profile output quantities\\
365           \hline
366           \texttt{user\_check\_parameters} & - - - & \texttt{check\_parameters} & check user-defined variables\\
367           \hline         
368           \texttt{user\_data\_output\_2d} & \texttt{av}, \texttt{variable}, \texttt{found}, \texttt{grid}, \texttt{local\_pf} & \texttt{data\_output\_2d} & output/calculation of additional user-defined quantities\\ 
369           \hline         
370           \texttt{user\_data\_output\_3d} & \texttt{av}, \texttt{variable}, \texttt{found}, \texttt{local\_pf}, \texttt{nz\_do} & \texttt{data\_output\_3d} & output/calculation of additional user-defined quantities\\
371           \hline         
372           \texttt{user\_data\_output\_dvrp} & \texttt{output\_variable}, \texttt{local\_pf} & \texttt{data\_output\_dvrp} & output of additional user-defined quantities\\
373           \hline
374           \texttt{user\_data\_output\_mask} & \texttt{av}, \texttt{variable}, \texttt{found}, \texttt{local\_pf} & \texttt{data\_output\_mask} & output of additional masked user-defined quantities\\
375           \hline
376           \texttt{user\_define\_netcdf\_grid} & \texttt{variable}, \texttt{found}, \texttt{grid\_x}, \texttt{grid\_y}, \texttt{grid\_z} & \texttt{netcdf} & defining the grid for additional output quantities\\
377           \hline
378           \texttt{user\_dvrp\_coltab} & \texttt{mode}, \texttt{variable} & \texttt{data\_output\_dvrp} & defining color tables for particles\\   
379           \hline         
380   \end{tabular}
381
382\end{frame}
383
384% Folie 9
385\begin{frame}
386   \frametitle{Complete List of User-Interface Routines (II)}
387   \tiny
388   \ \\
389   \begin{tabular}{|p{2.5cm}|p{2.4cm}|p{2.1cm}|p{3cm}|}
390      \hline
391           \textbf{Name} & \textbf{Arguments} & \textbf{Called from} & \textbf{Task}\\
392           \hline
393           \texttt{user\_header} & \texttt{io} & \texttt{header} & output user variables to header\\
394           \hline
395           \texttt{user\_init} & - - - & \texttt{init\_3d\_model} & e.g. reading from restart file\\
396           \hline
397           \texttt{user\_init\_3d\_model} & - - - & \texttt{init\_3d\_model} & special initializations\\
398           \hline
399           \texttt{user\_init\_grid} & \texttt{gls}, \texttt{nzb\_local} & \texttt{init\_grid} & defining a special topography\\
400           \hline         
401           \texttt{user\_init\_particles} & - - - & \texttt{init\_particles} & defining initial particle sources\\
402           \hline                 
403           \texttt{user\_init\_plant\_canopy} & - - - & \texttt{init\_3d\_model} & setting of leaf area density and canopy drag coefficient\\
404           \hline
405           \texttt{user\_last\_actions} & - - - & \texttt{palm} & e.g. output for restart runs\\
406           \hline         
407           \texttt{MODULE user (user\_module.f90)} & - - - & - - - & contains user defined variables\\
408           \hline                 
409           \texttt{user\_parin} &  & \texttt{parin} & reading user variables\\     
410           \hline         
411           \texttt{user\_particle\_attributes} & - - - & \texttt{advec\_particles} & defining particles attributes\\       
412           \hline
413           \texttt{user\_read\_restart\_data} & \texttt{i}, \texttt{nxlfa}, \texttt{nxl\_on\_file}, \texttt{nxrfa}, \texttt{nxr\_on\_file}, \texttt{nynfa}, \texttt{nyn\_on\_file}, \texttt{nysfa}, \texttt{nys\_on\_file}, \texttt{offset\_xa}, \texttt{offset\_ya}, \texttt{overlap\_count}, \texttt{tmp\_2d}, \texttt{tmp\_3d} & \texttt{read\_3d\_binary} & reading user-defined 2d/3d-arrays from the restart file\\         
414           \hline                 
415           \texttt{user\_spectra} & \texttt{mode}, \texttt{m}, \texttt{pr} & \texttt{data\_output\_spectra} & output/calculation of additional user-defined quantities\\           
416           \hline         
417           \texttt{user\_statistics} & \texttt{mode}, \texttt{sr}, \texttt{tn} & \texttt{flow\_statistics} & calculating additional horizontal averages + time series quantities\\             
418           \hline             
419   \end{tabular}
420   \ \\
421   \ \\
422   See PALM online documentation under \\
423   \textbf{http://palm.muk.uni-hannover.de/wiki/doc/app/userint}\\
424   for detailed explanations.
425
426\end{frame}
427
428% Folie 10
429\begin{frame}
430   \frametitle{Data Access / Exchange}
431   \footnotesize
432   \begin{itemize}
433      \item<2-> \textbf{Between the standard PALM code and the user-interface:}\\
434      \begin{itemize}
435         \scriptsize
436         \item<3-> by including the respective PALM modules in the user-interface subroutines.\\
437         \begin{center}
438            \includegraphics[scale=0.3]{user_defined_code_figures/data_access_exchange.png}
439         \end{center} 
440      \end{itemize}
441      \item<4-> \textbf{Within the user-interface:}
442      \begin{itemize}
443         \scriptsize
444         \item by the module \texttt{\textcolor{red}{user}} (file \texttt{user\underline{ }module.f90}),  which is used in every subroutine included in the interface.\\ \textbf{This module is (and should be) never used in the standard PALM code, in order to avoid data flow from the user interface to the\\ PALM default code!}
445      \end{itemize}
446   \end{itemize}
447
448\end{frame}
449
450% Folie 11
451\begin{frame}
452   \frametitle{Usage of \texttt{user\underline{ }actions} (I)}
453   \scriptsize
454   \begin{itemize}
455      \item<1-> \texttt{user\underline{ }actions} is designed to add additional terms to the prognostic equations or to carry out special actions at the beginning or the end of each timestep.
456      \vspace{2mm}
457      \item<2-> Therefore, several calls of \texttt{user\underline{ }actions} can be found in the default PALM routines \texttt{time\underline{ }integration} and \texttt{prognostic\underline{ }equations}. The place from which it is called is communicated to the routine by a string-argument, e.g.\\
458   \ \\
459   \quad \texttt{CALL user\underline{ }actions ( 'u-tendency' )}\\
460   \ \\
461        \onslide<3-> It means that this call is from a place within \texttt{prognostic\underline{ }equations}, where the tendencies for the u-component are calculated and integrated:
462   \end{itemize}
463   \vspace{-2mm}
464   \begin{center}
465      \includegraphics[scale=0.33]{user_defined_code_figures/user_actions_1.png}
466   \end{center}
467\end{frame}
468
469% Folie 12
470\begin{frame}
471   \frametitle{Usage of \texttt{user\underline{ }actions} (II)}
472   \scriptsize
473   \begin{itemize}
474      \item Additional tendencies have to be included by the user at the respective code line in \texttt{user\underline{ }actions}:
475   \end{itemize}
476   \begin{center}
477      \includegraphics[scale=0.35]{user_defined_code_figures/user_actions_2.png}
478   \end{center}
479\end{frame}
480
481% Folie 13
482\begin{frame}[t]
483   \frametitle{Usage of \texttt{user\underline{ }actions} (III)}
484   \scriptsize
485   \begin{columns}[T]
486      \begin{column}{1.15\textwidth}
487         \begin{itemize}
488            \item<1-> The different versions of \texttt{prognostic\underline{ }equations} (\texttt{prognostic\underline{ }equations\underline{ }cache}, \texttt{prognostic\underline{ }equations\underline{ }vector}) contain different calls of \texttt{user\underline{ }actions}:
489            \item<2-> From \texttt{prognostic\underline{ }equations\underline{ }vector}: \hspace{0.6em}\texttt{CALL user\underline{ }actions ( 'u-tendency' )}
490            \item<3-> From \texttt{prognostic\underline{ }equations},\\
491            \texttt{prognostic\underline{ }equations\underline{ }cache}:\hspace{4em}\texttt{CALL user\underline{ }actions ( i, j, 'u-tendency' )}
492            \vspace{3mm}
493            \item<4-> In case that \texttt{prognostic\underline{ }equations}\\
494            \texttt{prognostic\underline{ }equations\underline{ }cache} are\\
495            used, the user has to add his code in\\
496            the interface routine\\
497            \texttt{user\underline{ }actions\underline{ }ij}:
498            \vspace{3mm}
499            \item<5-> Here, only the \texttt{k}-loop (vertical direction)\\
500            has to be used, because loops over\\
501            i and j are carried out in\\
502            \texttt{prognostic\underline{ }equations\underline{ }cache}.
503         \end{itemize}
504      \end{column}
505   \end{columns}
506 
507   \uncover<4->{%
508   \begin{tikzpicture}[remember picture, overlay]
509      \node [shift={(8.3 cm,3.0cm)}]  at (current page.south west)
510         {%
511         \begin{tikzpicture}[remember picture, overlay]
512            \node[text width=14em] at (0,0) {\includegraphics[scale=0.3]{user_defined_code_figures/user_actions_3.png}};
513         \end{tikzpicture}
514         };
515    \end{tikzpicture}}
516   
517\end{frame}
518
519% Folie 14
520\begin{frame}
521   \frametitle{Steering the User-Interface}
522   \scriptsize
523   \begin{columns}[T]
524      \begin{column}{1.1\textwidth}
525         For steering the user-interface code, the user may want to add some additional variables and set their respective values within the parameter-file (e.g. \texttt{example\underline{ }cbl\underline{ }p3d}). This requires the following actions (example for a variable named \texttt{foo}):
526      \end{column}
527   \end{columns}
528   \vspace{1mm}
529      \begin{enumerate}
530         \item<1-> Add the variable name to module \texttt{user} in order to define it and to make it available in all user-interface subroutines. Set a default value for this variable.
531         \begin{center}
532            \includegraphics[scale=0.3]{user_defined_code_figures/steering_1.png}
533         \end{center}
534         \vspace{1mm}
535         \item<2-> Add the variable to the NAMELIST \texttt{/userpar/}. This NAMELIST already contains four predefined variables.
536         \begin{center}
537            \includegraphics[scale=0.3]{user_defined_code_figures/steering_2.png}
538         \end{center}
539         \vspace{1mm}
540         \item<3-> Add the NAMELIST \texttt{\&userpar} to the parameter file (e.g. \texttt{example\underline{ }cbl\underline{ }p3d}) and assign a value to this variable.         
541         \begin{center}
542            \includegraphics[scale=0.3]{user_defined_code_figures/steering_1.png}
543         \end{center}
544         \vspace{1mm}
545         \item<4-> Output the variable's value using \texttt{user\underline{ }header}.
546      \end{enumerate}
547     
548
549\end{frame}
550
551% Folie 15
552\begin{frame}
553   \frametitle{User-Defined Output}
554   \scriptsize
555   \begin{itemize}
556      \item<2-> A very typical request of users is the calculation and output of quantities which are not part of PALM's standard output (e.g. a 3D-array of the resolved-scale vertical heat (temperature) flux).
557      \vspace{2mm}
558      \item<3-> The default user interface includes a number of subroutines which allow the calculation of user-defined quantities and output of these quantities as profiles, timeseries, 2d cross section or 3d volume data. These are e.g.\\
559      \texttt{user\underline{ }check\underline{ }data\underline{ }output}, \texttt{user\underline{ }check\underline{ }data\underline{ }output\underline{ }pr},\\
560      \texttt{user\underline{ }define\underline{ }netcdf\underline{ }grid}, \texttt{user\underline{ }statistics},\\
561      \texttt{user\underline{ }3d\underline{ }data\underline{ }averaging}, \texttt{user\underline{ }data\underline{ }output\underline{ }2d},\\
562      \texttt{user\underline{ }data\underline{ }output\underline{ }3d}.
563      \vspace{2mm}
564      \item<4-> The respective subroutines contain, as an example, code lines (written as comment lines) for calculating and output the square of the u-component velocity.
565      \vspace{2mm}
566      \item<5-> These quantities are output to PALM‘s standard netCDF files, i.e.\\ \texttt{DATA\underline{ }1D\underline{ }PR\underline{ }NETCDF}, \texttt{DATA\underline{ }1D\underline{ }TS\underline{ }NETCDF}, \texttt{DATA\underline{ }2D\underline{ }XY\underline{ }NETCDF} or \texttt{DATA\underline{ }3D\underline{ }NETCDF}.
567      \vspace{2mm}
568      \item<6-> The online documentation gives very detailed instructions about how to modify the interface in order to output user-defined quantities under\\
569      \vspace{1mm}
570      \textbf{http://palm.muk.uni-hannover.de/wiki/doc/app/userint/output}
571   \end{itemize}
572\end{frame}
573
574% Folie 16
575\begin{frame}
576   \frametitle{User-Defined Data for Restart Runs (I)}
577   \scriptsize
578   \begin{itemize}
579      \item It might be neccessary to save the values of user-defined variables at the end of a model run in order to use them for a restart run.\\
580      \ \\
581      This can be done using the routine \texttt{user\underline{ }last\underline{ }actions}.\\
582      \grqq \texttt{14}\grqq\, is the file-id for the restart file (local filename \texttt{BINOUT}):
583   \end{itemize}
584   \begin{center}
585      \includegraphics[scale=0.3]{user_defined_code_figures/restart_1.png}
586   \end{center}
587\end{frame}
588
589% Folie 17
590\begin{frame}
591   \frametitle{User-Defined Data for Restart Runs (II)}
592   \scriptsize
593   \begin{itemize}
594      \item Additionally, these variables have to be read from the restart file (file-id \grqq \texttt{13}\grqq\,, local filename \texttt{BININ}) by adding code to the routine \texttt{user\underline{ }read\underline{ }restart\underline{ }data}:
595   \end{itemize}
596   \begin{center}
597      \includegraphics[scale=0.3]{user_defined_code_figures/restart_2.png}
598   \end{center}
599\end{frame}
600
601% Folie 18
602\begin{frame}
603   \frametitle{Using the User-Interface with \texttt{mrun}}
604   \scriptsize
605   \begin{columns}[T]
606      \begin{column}{1.1\textwidth}
607         \vspace{-1mm}
608         \textbf{Users can add their own (modified) user-interface to a PALM-run by carrying out the following steps:}
609         \begin{enumerate}
610            \item<2-> Copy the default (empty) user-interface files that you need (e.g. user\underline{ }module.f90, user\underline{ }parin.f90, user\underline{ }actions.f90) to a directory of your choice, e.g.:\\
611            \tiny
612                 \quad \texttt{cd \~{ }/palm/current\underline{ }version}\\
613                 \quad \texttt{mkdir -p USER\underline{ }CODE/example\underline{ }cbl}\\
614                 \quad \texttt{cp trunk/SOURCE/user\underline{ }module.f90  USER\underline{ }CODE/example\underline{ }cbl/user\underline{ }module.f90}\\
615                 \quad \texttt{cp trunk/SOURCE/user\underline{ }parin.f90\hspace{1em}USER\underline{ }CODE/example\underline{ }cbl/user\underline{ }parin.f90}\\
616            \quad \texttt{...}
617            \scriptsize
618            \vspace{-1mm}
619            \item<3-> Set an additional path in the configuration file \texttt{.mrun.config} to allow \texttt{mrun} to find and include this file:\\
620            \tiny
621                 \quad \texttt{\%add\underline{ }source\underline{ }path \hspace{1em} \$base\underline{ }directory/USER\underline{ }CODE/\$fname}
622                 \scriptsize
623                 \item<4-> Modify the interface routines according to your needs.
624                 \item<5-> Start a PALM run by executing\\
625                 \tiny
626                 \quad  \texttt{mrun -d example\underline{ }cbl ...}\\
627                 \scriptsize
628                 The files user\underline{ }*.f90 will be automatically compiled within the job / interactive run and will replace the respective PALM default user-interface files.
629              \end{enumerate}
630              \vspace{-2mm}
631         \begin{itemize}
632                 \item<6-> \textbf{The modified user-interface file cannot be pre-compiled by using} \texttt{mbuild}!
633                 \item<7-> The above method allows to use different user-interfaces for different runs. Just store the respective interface-files in subdirectories \texttt{USER\underline{ }CODE/abcd}, \texttt{USER\underline{ }CODE/cdef}, etc. and start \texttt{mrun} with option \grqq \texttt{-d abcd}\grqq, \grqq \texttt{-d cdef}\grqq, etc.
634         \end{itemize}
635
636      \end{column}
637   \end{columns} 
638   
639\end{frame}
640
641\end{document}
Note: See TracBrowser for help on using the repository browser.