% $Id: user_defined_code.tex 1226 2013-09-18 13:19:19Z fuhrmann $ \input{header_tmp.tex} %\input{../header_lectures.tex} \usepackage[utf8]{inputenc} \usepackage{ngerman} \usepackage{pgf} \usetheme{Dresden} \usepackage{subfigure} \usepackage{units} \usepackage{multimedia} \usepackage{hyperref} \newcommand{\event}[1]{\newcommand{\eventname}{#1}} \usepackage{xmpmulti} \usepackage{tikz} \usetikzlibrary{shapes,arrows,positioning} %\usetikzlibrary{decorations.markings} %neues paket %\usetikzlibrary{decorations.pathreplacing} %neues paket \def\Tiny{\fontsize{4pt}{4pt}\selectfont} \usepackage{amsmath} \usepackage{amssymb} \usepackage{multicol} \usepackage{pdfcomment} \usepackage{graphicx} \usepackage{listings} \lstset{showspaces=false,language=fortran,basicstyle= \ttfamily,showstringspaces=false,captionpos=b} \institute{Institut für Meteorologie und Klimatologie, Leibniz Universität Hannover} \date{last update: \today} \event{PALM Seminar} \setbeamertemplate{navigation symbols}{} \setbeamertemplate{footline} { \begin{beamercolorbox}[rightskip=-0.1cm]& {\includegraphics[height=0.65cm]{imuk_logo.pdf}\hfill \includegraphics[height=0.65cm]{luh_logo.pdf}} \end{beamercolorbox} \begin{beamercolorbox}[ht=2.5ex,dp=1.125ex, leftskip=.3cm,rightskip=0.3cm plus1fil]{title in head/foot} {\leavevmode{\usebeamerfont{author in head/foot}\insertshortauthor} \hfill \eventname \hfill \insertframenumber \; / \inserttotalframenumber} \end{beamercolorbox} \begin{beamercolorbox}[colsep=1.5pt]{lower separation line foot} \end{beamercolorbox} } %\logo{\includegraphics[width=0.3\textwidth]{luhimuk_logo.pdf}} \title[The PALM User-Interface]{The PALM User-Interface} \author{Siegfried Raasch} \begin{document} % Folie 1 \begin{frame} \titlepage \end{frame} \section{The PALM User-Interface} \subsection{The PALM User-Interface} % Folie 2 \begin{frame} \frametitle{Purpose of the User-Interface} \scriptsize \begin{itemize} \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. \end{itemize} \vspace{2mm} \onslide<3-> \textbf{Problem:} \begin{itemize} \item<3-> If a new PALM version is released (current release is 3.9) and the user wants to use it, he would have to add his modifications to the new release again. \end{itemize} \vspace{3mm} \onslide<4-> \textbf{Solution:} \begin{itemize} \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. \item<5-> By using the user-interface, the standard code does not have to be modified by the user in most of all cases. \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. \end{itemize} \end{frame} % Folie 3 \begin{frame} \frametitle{General Structure of the User-Interface} \tikzstyle{yellow} = [rectangle, draw, fill=yellow!30, text width=0.7\textwidth, font=\Tiny] \scriptsize \begin{itemize} \item<1-> All routines can be found under \texttt{.../trunk/SOURCE}. \item<2-> There is one file for each routine. Filenames are \texttt{user\underline{ }*.f90}.\\ Example: \texttt{user\underline{ }last\underline{ }actions.f90} \end{itemize} \onslide<3-> \begin{center} \begin{tikzpicture}[auto] \node[yellow]{~\texttt{SUBROUTINE user\_last\_actions} \\ \par\medskip \texttt{!------------------------------------------------------------------------------!}\\ \texttt{!}\\ \texttt{! Description:}\\ \texttt{! ------------}\\ \texttt{! Execution of user-defined actions at the end of a job.}\\ \texttt{!------------------------------------------------------------------------------!}\\ \par\medskip ~~~~\texttt{USE control\_parameters}\\ ~~~~\texttt{USE user}\\ \par\medskip ~~~~\texttt{IMPLICIT NONE}\\ \par\medskip \texttt{!}\\ \texttt{!-- Here the user-defined actions at the end of a job follow.}\\ \texttt{!-- Sample for user-defined output:}\\ \vspace{0.5mm} ~~~~\texttt{IF ( write\_binary(1:4) == 'true' ) THEN}\\ \vspace{0.5mm} \texttt{!~~~~~~~IF ( ALLOCATED( u2\_av ) ) THEN}\\ \vspace{0.5mm} \texttt{!~~~~~~~~~~WRITE ( 14 ) 'u2\_av~~~~~~~~~~~~~~~'; WRITE ( 14 ) u2\_av}\\ \vspace{0.5mm} \texttt{!~~~~~~~ENDIF}\\ \par\medskip ~~~~~~~\texttt{WRITE ( 14 ) '*** end user ***~~~~'}\\ \par\medskip ~~~~\texttt{ENDIF}\\ \par\medskip ~\texttt{END SUBROUTINE user\_last\_actions}}; \end{tikzpicture} \end{center} % \includegraphics[scale=0.3]{user_defined_code_figures/user_last_actions.png}\\ \end{frame} % Folie 4 \begin{frame} \frametitle{Embedding of User-Interface Routines} \tikzstyle{yellow} = [rectangle, draw, fill=yellow!30, text width=0.7\textwidth, font=\Tiny] \scriptsize \begin{itemize} \item<1-> The user-interface routines are called from specific, well-defined locations in the standard PALM code.\\ \ \\ Example from \texttt{palm.f90}: \end{itemize} \onslide<2-> \begin{center} \begin{tikzpicture}[auto] \node[yellow]{~\texttt{...}\\ \vspace{0.5mm} \texttt{!}\\ \texttt{!-- If required, final user-defined actions, and}\\ \texttt{!-- last actions on the open files and close files. Unit 14 was opened}\\ \texttt{!-- in write\_3d\_binary but it is closed here, to allow writing on this}\\ \texttt{!-- unit in routine user\_last\_actions.}\\ \vspace{0.5mm} ~~~~\texttt{CALL cpu\_log( log\_point(4), 'last actions', 'start' )}\\ ~~~~\texttt{DO i = 0, io\_blocks-1}\\ ~~~~~~~\texttt{IF ( i == io\_group ) THEN}\\ ~~~~~~~~~~\texttt{\textcolor{blue}{CALL user\_last\_actions}}\\ \vspace{0.5mm} ~~~~~~~~~~\texttt{IF ( write\_binary(1:4) == 'true' ) CALL close\_file( 14 )}\\ ~~~~~~~\texttt{ENDIF}\\ \vspace{0.5mm} \texttt{\#if defined( \_\_parallel )}\\ ~~~~~~~\texttt{CALL MPI\_BARRIER( comm2d, ierr )}\\ \vspace{0.5mm} \texttt{\#endif}\\ \vspace{0.5mm} ~~~~\texttt{ENDDO}\\ \vspace{0.5mm} ~~~~\texttt{CALL close\_file( 0 )}\\ \vspace{0.5mm} ~~~~\texttt{CALL close\_dvrp}\\ ~~~~\texttt{CALL cpu\_log( log\_point(4), 'last actions', 'stop' )}\\ \vspace{1mm} ~\texttt{...}\\ \vspace{1mm} \texttt{!}\\ \texttt{!-- Take final CPU-time for CPU-time analysis}\\ ~~~~\texttt{CALL cpu\_log( log\_point(1), 'total', 'stop' )}\\ ~~~~\texttt{CALL cpu\_statistics}\\ \texttt{\#if defined( \_\_parallel )}\\ ~~~~\texttt{CALL MPI\_FINALIZE( ierr )}\\ \vspace{0.5mm} \texttt{\#endif}\\ \par\medskip ~\texttt{END PROGRAM palm}}; \end{tikzpicture} \end{center} % \includegraphics[scale=0.33]{user_defined_code_figures/embedding.png}\\ \end{frame} % Folie 5 \begin{frame} \frametitle{Embedding of User-Interface Routines\\ Flow Chart Overview (I): Initial Steps} \scriptsize \begin{tikzpicture}[scale=0.8, transform shape] % Define colours \tikzstyle{green} = [draw, fill=green!30, text width=7.1em, text centered, minimum height=1.6em] \tikzstyle{green1} = [draw, fill=green!30, text width=12em, text centered, minimum height=1.6em] \tikzstyle{green2} = [draw, fill=green!30, text width=10em, text centered, minimum height=1.6em] \tikzstyle{yellow} = [draw, fill=yellow!30, text width=7.1em, text centered, minimum height=1.6em] \tikzstyle{orange} = [draw, fill=orange!60, text width=7.1em, text centered] % Define coordinates and draw nodes \node[yellow, text width=5em] (PALM) at (0,0.1) {PALM}; \coordinate (A) at (0,-0.7); \node[yellow, right=0.6cm of A] (parin) {parin}; \node[green, right=1mm of parin] (userparin) {user\_parin}; \draw[-] (parin) -- (userparin); \coordinate[below=0.6cm of A] (B); \node[yellow, right=0.6cm of B] (initgrid) {init\_grid}; \node[green, right=1mm of initgrid] (userinigrid) {user\_init\_grid}; \draw[-] (initgrid) -- (userinigrid); \coordinate[below=0.6cm of B] (C); \node[yellow, right=0.6cm of C] (checkparam) {check\_parameters}; \coordinate[below=0.3cm of checkparam] (D); \node[green1, right=0.6cm of D] (usercheckdataout) {user\_check\_data\_output/\_pr}; \coordinate[below=0.55cm of D] (E); \node[green1, right=0.6cm of E] (usercheckparam) {user\_check\_parameters}; \coordinate[below=1.7cm of C] (F); \node[yellow, right=0.6cm of F] (init3dmodel) {init\_3d\_model}; \coordinate[below=0.3cm of init3dmodel] (G); \node[green2, right=0.6cm of G] (userinit3d) {user\_init\_3d\_model}; \coordinate[below=0.55cm of G] (H); \node[yellow, right=0.6cm of H] (read3dbin) {read\_3d\_binary}; \coordinate[below=0.3cm of read3dbin] (I); \node[green1, right=0.6cm of I] (userreadrestart) {user\_read\_restart\_data}; \coordinate[below=1.15cm of H] (J); \node[green1, right=0.6cm of J] (userinitplan) {user\_init\_plant\_canopy}; \coordinate[below=0.6cm of J] (K); \node[yellow, right=0.6cm of K] (lpminit) {lpm\_init}; \node[green, right=1mm of lpminit] (userlpminit) {user\_lpm\_init}; \draw[-] (lpminit) -- (userlpminit); \coordinate[below=0.6cm of K] (L); \node[green, right=0.6cm of L] (userinit) {user\_init}; \coordinate[below=4.05cm of F] (M); \node[yellow, right=0.6cm of M] (header) {header}; \node[green, right=1mm of header] (userheader) {user\_header}; \draw[-] (header) -- (userheader); % % Draw lines \draw[-, thick] (PALM) -- (0,-7.8); \draw[dotted, thick] (0,-8.2) -- (0,-7.8); \draw[-] (A) -- (parin); \draw[-] (B) -- (initgrid); \draw[-] (C) -- (checkparam); \draw[-] (checkparam.south) |- (usercheckdataout.west); \draw[-] (checkparam.south) |- (usercheckparam.west); \draw[-] (F) -- (init3dmodel); \draw[-,dashed] (init3dmodel.south) |- (userinit3d.west); \draw[-,dashed] (init3dmodel.south) |- (read3dbin.west); \draw[-] (read3dbin.south) |- (userreadrestart.west); \draw[-,dashed] (init3dmodel.south) |- (userinitplan); \draw[-,dashed] (init3dmodel.south) |- (lpminit); \draw[-] (init3dmodel.south) |- (userinit); \draw[-] (M) -- (header); \end{tikzpicture} \end{frame} % Folie 6 \begin{frame} \frametitle{Embedding of User-Interface Routines\\ Flow Chart Overview (II): Time Integration Loop} \scriptsize \begin{tikzpicture}[scale=0.7, transform shape] % Define colours \tikzstyle{green} = [draw, fill=green!30, text width=7.1em, text centered, minimum height=1.6em] \tikzstyle{green1} = [draw, fill=green!30, text width=10em, text centered, minimum height=1.6em] \tikzstyle{yellow} = [draw, fill=yellow!30, text width=7.1em, text centered, minimum height=1.6em] \tikzstyle{orange} = [draw, fill=orange!60, text width=7.1em, text centered] \tikzstyle{orange1} = [draw, fill=orange!80, text width=11em, text centered] \definecolor{grey}{rgb}{0.25,0.25,0.25} % Define coordinates and draw nodes \node[draw, text width=25em,minimum height=4.0em,fill=black!15] (progframe) at (5.75,-1.5) {}; \coordinate (A) at (0,0); \node[orange, right=0.6cm of A] (timeint) {time\_integration}; \coordinate[below=0.3cm of timeint] (B); \coordinate[below=0.8cm of timeint] (C); \coordinate[right=2cm of C] (D); \coordinate[right=3.8cm of D] (E); \node[green, right=0.6cm of B, text width=14em] (useractions1) {\textcolor{blue}{user\_actions\_(\textit{'before\_timestep'})}}; \node[orange1, below=0.2cm of D] (progeq) {prognostic\_equations}; \node[orange1, below=0.2cm of E] (progeqfast) {prognostic\_equations\_fast}; \node[draw, fill=red, text width=4em] at (8.6,-0.8) {\textcolor{white}{standard advection}}; \node[green, right=0.3cm of progframe, text width=14em] (useractions2) {\textcolor{blue}{user\_actions\_(\textit{'*\_tendency'})}}; \coordinate[below=2.3cm of timeint] (F); \coordinate[below=2.9cm of timeint] (G); \coordinate[below=3.5cm of timeint] (H); \coordinate[below=4.1cm of timeint] (I); \node[yellow, right=0.6cm of F] (lpm) {lpm}; \node[green, right=0.9cm of lpm, text width=10em] (userlpmadvec) {user\_lpm\_advec}; \node[yellow, right=0.6cm of G] (exchangehoriz) {exchange\_horiz}; % \node[yellow, right=0.0cm of exchangehoriz] (asselin) {asselin\_filter}; \node[yellow, right=0.6cm of H] (swaptimelevel) {swap\_timelevel}; \node[yellow, right=0.6cm of I] (pres) {pres}; \coordinate[below=0.3cm of pres] (J); \coordinate[below=5.1cm of timeint] (K); \coordinate[below=5.7cm of timeint] (L); \coordinate[below=6.3cm of timeint] (M); \coordinate[below=6.9cm of timeint] (N); \coordinate[below=8.2cm of timeint] (O); \coordinate[below=8.8cm of timeint] (P); % \node[yellow, right=0.6cm of K] (prandtlfluxes) {prandtl\_fluxes}; \node[green, right=0.6cm of K, text width=14em] (useractions3) {\textcolor{blue}{user\_actions\_(\textit{'after\_integration'})}}; % \node[yellow, right=0.6cm of L] (diffusivities) {diffusivities}; % \node[yellow, right=0.6cm of L] (checkrestart) {check\_for\_restart}; \node[yellow, right=0.6cm of L] (flowstat) {flow\_statistics}; \node[green, right=0.6cm of flowstat] (userstat2) {user\_statistics}; \node[yellow, right=0.6cm of M] (sum3ddata) {sum\_up\_3d\_data}; \node[green1, right=0.6cm of sum3ddata] (user3ddataav) {user\_3d\_data\_averaging}; \node[green, right=0.6cm of O, text width=14em] (useractions4) {\textcolor{blue}{user\_actions\_(\textit{'after\_timestep'})}}; % \node[yellow, right=0.6cm of P] (timestep) {timestep}; \node[yellow, right=0.2cm of user3ddataav] (dataoutput) {data\_output\_***}; \node[green, right=0.2cm of dataoutput] (userdvrpcoltab) {user\_dvrp\_coltab}; \coordinate[below=0.2cm of dataoutput] (Q); \coordinate[right=0.4cm of Q] (R); \coordinate[right=3.0cm of R] (S); \node[green, below=0.2cm of R, text width=9em] (output2d) {user\_data\_output\_2d}; \node[green, below=0.2cm of S, text width=9em] (output3d) {user\_data\_output\_3d}; \draw[dotted, thick] (0,0.05) -- (0,0.3); \draw[-, thick] (0,0.05) -- (0,-8.8); \draw[dotted, thick] (0,-9.2) -- (0,-8.8); \draw[-, thick] (A) -- (timeint); \draw[-, thick] (timeint) -- (P); \draw[-, thick] (B) -- (useractions1); \draw[-, thick] (C) -- (D); \draw[-, thick] (progeq) -- (D); \draw[-, thick, color=red] (D) -- (E); \draw[->, thick, color=red] (E) -- (progeqfast); \draw[-, thick] (progframe) -- (useractions2); \draw[-, thick] (F) -- (lpm); \draw[-, thick] (userlpmadvec) -- (lpm); \draw[-, thick] (G) -- (exchangehoriz); \draw[-, thick] (H) -- (swaptimelevel); \draw[-, thick] (I) -- (pres); \draw[dotted, thick] (pres) -- (J); % \draw[-, thick] (K) -- (prandtlfluxes); \draw[-, thick] (K) -- (useractions3); \draw[-, thick] (L) -- (flowstat); \draw[-, thick] (M) -- (sum3ddata); \draw[-, thick] (sum3ddata) -- (user3ddataav); \draw[-, thick] (userstat2) -- (flowstat); \draw[-, thick] (O) -- (useractions4); % \draw[-, thick] (O) -- (timestep); \draw[-, thick] (dataoutput) -- (Q); \draw[-, thick] (S) -- (Q); \draw[-, thick] (R) -- (output2d); \draw[-, thick] (S) -- (output3d); \end{tikzpicture} \end{frame} % Folie 7 \begin{frame} \frametitle{Embedding of User-Interface Routines\\ Flow Chart Overview (III): Final Steps} \scriptsize \begin{tikzpicture}[scale=0.8, transform shape] % Define colours \tikzstyle{green} = [draw, fill=green!30, text width=7.1em, text centered, minimum height=1.6em] \tikzstyle{yellow} = [draw, fill=yellow!30, text width=7.1em, text centered, minimum height=1.6em] \tikzstyle{orange} = [draw, fill=orange!60, text width=7.1em, text centered] % Define coordinates and draw nodes \node[green, text width=5em] (PALM) at (0,0.1) {PALM}; \coordinate (A) at (0,-0.7); \node[orange, right=0.6cm of A] (timeint) {time\_integration}; \coordinate[below=0.5cm of timeint] (B); \coordinate[below=1.0cm of timeint] (C); \coordinate[below=2.5cm of PALM] (D); \node[yellow, right=0.6cm of D] (write3dbinary) {write\_3d\_binary}; \node[yellow, right=0.9cm of write3dbinary] (writevarlist) {write\_var\_list}; \coordinate[below=3.5cm of PALM] (E); \coordinate[below=4.1cm of PALM] (F); \coordinate[below=4.7cm of PALM] (G); \node[yellow, right=0.6cm of E] (header) {header}; \node[green, right=0.6cm of F] (userlastactions) {user\_last\_actions}; \node[yellow, right=0.6cm of G] (cpustat) {cpu\_statistics}; % Draw lines \draw[-, thick] (PALM) -- (G); \draw[-, thick] (A) -- (timeint); \draw[-, thick] (B) -- (timeint); \draw[dotted, thick] (B) -- (C); \draw[dashed, thick] (D) -- (write3dbinary); \draw[-, thick] (write3dbinary) -- (writevarlist); \draw[-, thick] (E) -- (header); \draw[-, thick] (F) -- (userlastactions); \draw[-, thick] (G) -- (cpustat); \end{tikzpicture} \end{frame} % Folie 8 \begin{frame} \frametitle{Complete List of User-Interface Routines (I)} \tiny \begin{tabular}{|p{2.5cm}|p{2.4cm}|p{2.1cm}|p{3cm}|} \hline \textbf{Name} & \textbf{Arguments} & \textbf{Called from} & \textbf{Task}\\ \hline \texttt{user\_3d\_data\_averaging} & \texttt{mode}, \texttt{variable} & \texttt{average\_3d\_data} + \texttt{sum\_up\_3d\_data} & temporal averaging for user-defined quantities\\ \hline \texttt{user\_actions} \texttt{user\_actions} & \texttt{location} \,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\,\, \texttt{i}, \texttt{j}, \texttt{location} & \texttt{time\_integration} + \texttt{prognostic\_equations} & e.g. additional forces to be included in the prognostic equations\\ \hline \texttt{user\_dummy (user\_additional \_routines.f90)} & - - - & - - - & for additional subroutines defined by the user\\ \hline \texttt{user\_check\_data\_output} & \texttt{variable}, \texttt{unit} & \texttt{check\_parameters} + \texttt{init\_masks}& check the user-defined output quantities\\ \hline \texttt{user\_check\_data\_output\_pr} & \texttt{variable}, \texttt{var\_count}, \texttt{unit} & \texttt{check\_parameters} & check the user-defined profile output quantities\\ \hline \texttt{user\_check\_parameters} & - - - & \texttt{check\_parameters} & check user-defined variables\\ \hline \texttt{user\_data\_output\_2d} & \texttt{av}, \texttt{variable}, \texttt{found}, \texttt{grid}, \texttt{local\_pf}, \texttt{two\_d} & \texttt{data\_output\_2d} & output/calculation of additional user-defined quantities\\ \hline \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\\ \hline \texttt{user\_data\_output\_dvrp} & \texttt{output\_variable}, \texttt{local\_pf} & \texttt{data\_output\_dvrp} & output of additional user-defined quantities\\ \hline \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\\ \hline \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\\ \hline \texttt{user\_dvrp\_coltab} & \texttt{mode}, \texttt{variable} & \texttt{data\_output\_dvrp} & defining color tables for particles\\ \hline \texttt{user\_header} & \texttt{io} & \texttt{header} & output user variables to header\\ \hline \texttt{user\_init} & - - - & \texttt{init\_3d\_model} & e.g. reading from restart file\\ \hline \end{tabular} \end{frame} % Folie 9 \begin{frame} \frametitle{Complete List of User-Interface Routines (II)} \tiny \ \\ \begin{tabular}{|p{2.5cm}|p{2.4cm}|p{2.1cm}|p{3cm}|} \hline \textbf{Name} & \textbf{Arguments} & \textbf{Called from} & \textbf{Task}\\ \hline \texttt{user\_init\_3d\_model} & - - - & \texttt{init\_3d\_model} & special initializations\\ \hline \texttt{user\_init\_grid} & \texttt{gls} & \texttt{init\_grid} & defining a special topography\\ \hline \texttt{user\_init\_plant\_canopy} & - - - & \texttt{init\_3d\_model} & setting of leaf area density and canopy drag coefficient\\ \hline \texttt{user\_last\_actions} & - - - & \texttt{palm} & e.g. output for restart runs\\ \hline \texttt{user\_lpm\_advec} & - - - & \texttt{lpm} & modification of particles after advection \\ \hline \texttt{user\_lmp\_init} & - - - & \texttt{lpm\_init} & defining initial particle sources \\ \hline \texttt{user\_lpm\_set\_attributes} & - - - & \texttt{lpm} & defining particles attributes \\ \hline \texttt{MODULE user (user\_module.f90)} & - - - & - - - & contains user defined variables\\ \hline \texttt{user\_parin} & & \texttt{parin} & reading user variables\\ \hline \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\\ \hline \texttt{user\_spectra} & \texttt{mode}, \texttt{m}, \texttt{pr} & \texttt{calc\_spectra} + \texttt{data\_output\_spectra} & output/calculation of additional user-defined quantities\\ \hline \texttt{user\_statistics} & \texttt{mode}, \texttt{sr}, \texttt{tn} & \texttt{flow\_statistics} & calculating additional horizontal averages + time series quantities\\ \hline \end{tabular} \ \\ \ \\ See PALM online documentation under \\ \textbf{http://palm.muk.uni-hannover.de/wiki/doc/app/userint}\\ for detailed explanations. \end{frame} % Folie 10 \begin{frame} \frametitle{Data Access / Exchange} \tikzstyle{yellow} = [rectangle, draw, fill=yellow!30, text width=0.6\textwidth, font=\tiny] \footnotesize \begin{itemize} \item<2-> \textbf{Between the standard PALM code and the user-interface:}\\ \begin{itemize} \scriptsize \item<3-> by including the respective PALM modules in the user-interface subroutines.\\ \begin{center} % \includegraphics[scale=0.3]{user_defined_code_figures/data_access_exchange.png} \begin{tikzpicture}[auto] \node[yellow]{\texttt{SUBROUTINE user\_actions( location )} \\ \par\medskip ~~~~~\texttt{\textcolor{blue}{USE arrays\_3d}} \\ ~~~~~\texttt{\textcolor{blue}{USE control\_parameters}} \\ ~~~~~\texttt{\textcolor{blue}{USE cpulog}} \\ ~~~~~\texttt{\textcolor{blue}{USE indices}} \\ ~~~~~\texttt{\textcolor{blue}{USE interfaces}} \\ ~~~~~\texttt{\textcolor{blue}{USE pegrid}} \\ ~~~~~\texttt{\textcolor{red}{USE user}} \\ \par\medskip ~~~~~\texttt{IMPLICIT NONE} \\ \par\medskip ~~~~~\texttt{CHARACTER (LEN=$^\ast$) :: location} \\ \par\medskip ~~~~~\texttt{INTEGER :: i, j, k}}; \end{tikzpicture} \end{center} \end{itemize} \item<4-> \textbf{Within the user-interface:} \begin{itemize} \scriptsize \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!} \end{itemize} \end{itemize} \end{frame} % Folie 11 \begin{frame} \frametitle{Usage of \texttt{user\underline{ }actions} (I)} \tikzstyle{yellow} = [rectangle, draw, fill=yellow!30, text width=0.7\textwidth, font=\tiny] \scriptsize \begin{itemize} \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. \vspace{1.8mm} \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.\\ \ \\ \quad \texttt{CALL user\underline{ }actions ( 'u-tendency' )}\\ \ \\ \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: \end{itemize} \vspace{-3mm} \begin{center} \begin{tikzpicture}[auto] \node[yellow] {\texttt{DO i = nxl, nxr} \\ ~~~\texttt{DO j = nys, nyn} \\ \texttt{...} \\ ~~~~~~\texttt{CALL diffusion\_u( i, j )}\\ ~~~~~~\texttt{CALL coriolis( i, j, 1 )} \\ \texttt{...}\\ ~~~~~~\texttt{\textcolor{blue}{CALL user\_actions( i, j, 'u-tendency' )}}\\ \texttt{!} \\ \texttt{!-- Prognostic equation for u-velocity component} \\ ~~~~~~\texttt{DO k = nzb\_u\_inner(j,i)+1, nzt} \\ ~~~~~~~~~\texttt{u\_p(k,j,i) = u(k,j,i) + dt\_3d * ( tsc(2) * tend(k,j,i) + \&} \\ \hspace{4.08cm} \texttt{tsc(3) * tu\_m(k,j,i) ) \&} \\ \hspace{2.93cm} \texttt{- tsc(5) * rdf(k) * ( u(k,j,i) - ug(k) )}\\ ~~~~~~\texttt{ENDDO} \\ \texttt{...}}; \end{tikzpicture} \end{center} % \begin{center} % \includegraphics[scale=0.33]{user_defined_code_figures/user_actions_1.png} % \end{center} \end{frame} % Folie 12 \begin{frame} \frametitle{Usage of \texttt{user\underline{ }actions} (II)} \tikzstyle{yellow} = [rectangle, draw, fill=yellow!30, text width=0.7\textwidth, font=\tiny] \scriptsize \begin{itemize} \item Additional tendencies have to be included by the user at the respective code line in \texttt{user\underline{ }actions}: \end{itemize} \begin{center} \begin{tikzpicture}[auto] \node[yellow]{~\texttt{SUBROUTINE user\_actions( location )}\\ \texttt{...}\\ \texttt{!}\\ \texttt{!-- Here the user-defined actions follow}\\ \texttt{!-- No calls for single grid points are allowed at locations before and}\\ \texttt{!-- after the timestep, since these calls are not within an i,j-loop}\\ ~~~~~~~\texttt{SELECT CASE ( location )}\\ \texttt{...}\\ ~~~~~~~~~~\texttt{CASE ( 'after\_timestep' )}\\ \texttt{!}\\ \texttt{!-- Enter actions to be done after every timestep here}\\ \par\medskip ~~~~~~~~~~\texttt{CASE ( 'u-tendency' )}\\ \texttt{!}\\ \texttt{!-- Enter actions to be done in the u-tendency term here}\\ ~~~~~~~~~~~~~\texttt{\textcolor{blue}{DO i = nxl, nxr}}\\ ~~~~~~~~~~~~~~~~\texttt{\textcolor{blue}{DO j = nys, nyn}}\\ ~~~~~~~~~~~~~~~~~~~\texttt{\textcolor{blue}{DO k = nxb+1, nzt}}\\ ~~~~~~~~~~~~~~~~~~~~~~~~~\texttt{\textcolor{blue}{tend(k,j,i) = tend(k,j,i) - const * u(k,j,i) ...}}\\ ~~~~~~~~~~~~~~~~~~~\texttt{\textcolor{blue}{ENDDO}}\\ ~~~~~~~~~~~~~~~~\texttt{\textcolor{blue}{ENDDO}}\\ ~~~~~~~~~~~~~\texttt{\textcolor{blue}{ENDDO}}\\ \par\bigskip ~~~~~~~~~~\texttt{CASE ( 'v-tendency' )}\\ \texttt{...}}; \end{tikzpicture} % \includegraphics[scale=0.35]{user_defined_code_figures/user_actions_2.png} \end{center} \end{frame} % Folie 13 \begin{frame}[t] \frametitle{Usage of \texttt{user\underline{ }actions} (III)} \tikzstyle{yellow} = [rectangle, draw, fill=yellow!30, text width=0.5\textwidth, font=\Tiny] \scriptsize \begin{columns}[T] \begin{column}{1.15\textwidth} \begin{itemize} \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}: \item<2-> From \texttt{prognostic\underline{ }equations\underline{ }vector}: \hspace{0.6em}\texttt{CALL user\underline{ }actions ( 'u-tendency' )} \item<3-> From \texttt{prognostic\underline{ }equations},\\ \texttt{prognostic\underline{ }equations\underline{ }cache}:\hspace{4em}\texttt{CALL user\underline{ }actions ( i, j, 'u-tendency' )} \vspace{3mm} \item<4-> In case that \texttt{prognostic\underline{ }equations}\\ \texttt{prognostic\underline{ }equations\underline{ }cache} are\\ used, the user has to add his code in\\ the interface routine\\ \texttt{user\underline{ }actions\underline{ }ij}: \vspace{3mm} \item<5-> Here, only the \texttt{k}-loop (vertical direction)\\ has to be used, because loops over\\ i and j are carried out in\\ \texttt{prognostic\underline{ }equations\underline{ }cache}. \end{itemize} \end{column} \end{columns} \uncover<4->{% \begin{tikzpicture}[remember picture, overlay] \node [yellow,shift={(9.2 cm,3.0cm)}] at (current page.south west){~\texttt{SUBROUTINE user\_actions\_ij( i, j, location )}\\ \par\medskip ~~~\texttt{USE control\_parameters}\\ ~~~\texttt{USE pegrid}\\ ~~~\texttt{USE user}\\ \par\medskip ~~~\texttt{IMPLICIT NONE}\ \par\medskip ~~~\texttt{CHARACTER (LEN=*) :: location}\\ \par\medskip ~~~\texttt{INTEGER :: i, idum, j}\\ \par\medskip \texttt{!}\\ \texttt{!-- Here the user-defined actions follow}\\ \vspace{0.5mm} ~~~\texttt{SELECT CASE ( location )}\\ \par\medskip ~~~~~~\texttt{CASE ( 'u-tendency' )}\\ \texttt{!}\\ \texttt{!--Enter actions to be done in the u-tendency term here}\\ ~~~~~~~~~\texttt{\textcolor{blue}{DO k = nzb+1, nzt-1}}\\ ~~~~~~~~~~~~~~~\texttt{\textcolor{blue}{tend(k,j,i) = tend(k,j,i) + ...}}\\ ~~~~~~~~~\texttt{\textcolor{blue}{ENDDO}}\\ \par\medskip ~~~~~~\texttt{CASE ( 'v-tendency' )}}; % {% % \begin{tikzpicture}[remember picture, overlay] % % \node[text width=14em] at (0,0) {\includegraphics[scale=0.3]{user_defined_code_figures/user_actions_3.png}}; % \end{tikzpicture} % }; \end{tikzpicture}} \end{frame} % Folie 14 \begin{frame} \frametitle{Steering the User-Interface} \tikzstyle{yellow} = [rectangle, draw, fill=yellow!30, text width=0.7\textwidth, font=\Tiny] \scriptsize \begin{columns}[T] \begin{column}{1.1\textwidth} 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}): \end{column} \end{columns} \vspace{1mm} \begin{enumerate} \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. \begin{center} % \includegraphics[scale=0.3]{user_defined_code_figures/steering_1.png} \begin{tikzpicture} \node[yellow]{~\texttt{MODULE user}\\ \vspace{0.4mm} \texttt{...}\\ \vspace{0.4mm} ~\texttt{REAL \hspace{0.4cm}:: ~~\textcolor{blue}{foo = 0.0}}\\ \vspace{0.4mm} \texttt{...}\\ \vspace{0.4mm} ~\texttt{END MODULE user}}; \end{tikzpicture} \end{center} \vspace{1mm} \item<2-> Add the variable to the NAMELIST \texttt{/userpar/}. This NAMELIST already contains four predefined variables. \begin{center} % \includegraphics[scale=0.3]{user_defined_code_figures/steering_2.png} \begin{tikzpicture} \node[yellow]{~\texttt{SUBROUTINE user\_parin}\\ \vspace{0.4mm} \texttt{...}\\ \vspace{0.4mm} ~~~~~\texttt{NAMELIST ~~/userpar/ ~~ data\_output\_pr\_user, data\_output\_user,}\\ \vspace{0.4mm} \hspace{3cm}\texttt{\textcolor{blue}{foo}, region}\\ \vspace{0.4mm} \texttt{...}\\ \vspace{0.4mm} ~\texttt{END SUBROUTINE user\_parin}}; \end{tikzpicture} \end{center} \vspace{1mm} \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. \begin{center} % \includegraphics[scale=0.3]{user_defined_code_figures/steering_3.png} \begin{tikzpicture} \node[yellow]{~\texttt{\&inipar ~~~ nx = ... ~~/}\\ \vspace{0.4mm} ~\texttt{\&d3par ~~~ end\_time = 3600.0, ... ~~/}\\ \par\smallskip ~\texttt{\textcolor{blue}{\&userpar ~~foo = 12345.6 ~~/}}}; \end{tikzpicture} \end{center} \vspace{1mm} \item<4-> Output the variable's value using \texttt{user\underline{ }header}. \end{enumerate} \end{frame} % Folie 15 \begin{frame} \frametitle{User-Defined Output} \scriptsize \begin{itemize} \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). \vspace{2mm} \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.\\ \texttt{user\underline{ }check\underline{ }data\underline{ }output}, \texttt{user\underline{ }check\underline{ }data\underline{ }output\underline{ }pr},\\ \texttt{user\underline{ }define\underline{ }netcdf\underline{ }grid}, \texttt{user\underline{ }statistics},\\ \texttt{user\underline{ }3d\underline{ }data\underline{ }averaging}, \texttt{user\underline{ }data\underline{ }output\underline{ }2d},\\ \texttt{user\underline{ }data\underline{ }output\underline{ }3d}. \vspace{2mm} \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. \vspace{2mm} \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}. \vspace{2mm} \item<6-> The online documentation gives very detailed instructions about how to modify the interface in order to output user-defined quantities under\\ \vspace{1mm} \textbf{http://palm.muk.uni-hannover.de/wiki/doc/app/userint/output} \end{itemize} \end{frame} % Folie 16 \begin{frame} \frametitle{User-Defined Data for Restart Runs (I)} \tikzstyle{yellow} = [rectangle, draw, fill=yellow!30, text width=0.7\textwidth, font=\tiny] \scriptsize \begin{itemize} \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.\\ \ \\ This can be done using the routine \texttt{user\underline{ }last\underline{ }actions}.\\ \grqq \texttt{14}\grqq\, is the file-id for the restart file (local filename \texttt{BINOUT}): \end{itemize} \begin{center} % \includegraphics[scale=0.3]{user_defined_code_figures/restart_1.png} \begin{tikzpicture}[auto] \node[yellow]{~\texttt{SUBROUTINE user\_last\_actions}\\ \texttt{...}\\ ~~~~~\texttt{\textcolor{blue}{WRITE ( 14 ) 'foo \hspace{2cm}'; WRITE ( 14 ) foo}}\\ ~~~~~\texttt{\textcolor{blue}{WRITE ( 14 ) 'bar \hspace{2cm}'; WRITE ( 14 ) bar}} \par\smallskip ~~~~~\texttt{WRITE ( 14 ) '*** end user *** \hspace{0.66cm}'} \par\smallskip ~\texttt{END SUBROUTINE user\_last\_actions}}; \end{tikzpicture} \end{center} \end{frame} % Folie 17 \begin{frame} \frametitle{User-Defined Data for Restart Runs (II)} \tikzstyle{yellow} = [rectangle, draw, fill=yellow!30, text width=0.95\textwidth, font=\tiny] \scriptsize \begin{itemize} \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}: \end{itemize} \vspace{-2.7mm} \begin{center} % \includegraphics[scale=0.3]{user_defined_code_figures/restart_2.png} \begin{tikzpicture} \node[yellow]{\texttt{~SUBROUTINE user\_read\_restart\_data( i, nxlfa, nxl\_on\_file, nxrfa, nxr\_on\_file, \&} \\ \hspace{3.84cm}\texttt{nynfa, nyn\_on\_file, nysfa, nys\_on\_file, \&} \\ \hspace{3.84cm}\texttt{offset\_xa, offset\_ya, overlap\_count, \&} \\ \hspace{3.84cm}\texttt{tmp\_2d, tmp\_3d )}\\ \texttt{...} \\ ~~~~~\texttt{IF ( initializing\_actions == 'read\_restart\_data' ) THEN}\\ ~~~~~~~~~\texttt{READ ( 13 ) field\_char} \\ ~~~~~~~~~\texttt{DO WHILE ( TRIM( field\_char ) '*** end user ***' )}\\ \par\smallskip ~~~~~~~~~~~~~\texttt{nxlf = nxlfa(i,k)} \texttt{...} \\ ~~~~~~~~~~~~~\texttt{SELECT CASE ( TRIM( field\_char ) )}\\ \par\smallskip ~~~~~~~~~~~~~~~~~\texttt{CASE ( '\textcolor{blue}{foo}' )} \\ ~~~~~~~~~~~~~~~~~~~~~\texttt{IF ( .NOT. ALLOCATED( \textcolor{blue}{foo} ) ) THEN}\\ ~~~~~~~~~~~~~~~~~~~~~~~~~\texttt{ALLOCATE( \textcolor{blue}{foo}(nzb:nzt+1,nysg:nyng,nxlg:nxrg) )}\\ ~~~~~~~~~~~~~~~~~~~~~\texttt{ENDIF}\\ ~~~~~~~~~~~~~~~~~~~~~\texttt{IF ( k == 1 ) READ ( 13 ) tmp\_3d}\\ ~~~~~~~~~~~~~~~~~~~~~\texttt{\textcolor{blue}{foo}(:,nysc-nbgp:nync+nbgp,nxlc-nbgp:nxrc+nbgp) = \&} \\ \hspace{4.5cm}\texttt{tmp\_3d(:,nysf-nbgp:nynf+nbgp,nxlf-nbgp:nxrf+nbgp)}\\ \texttt{...}\\ ~~~~~~~~~~~~~\texttt{END SELECT}\\ \par\smallskip ~~~~~~~~~\texttt{ENDDO} \par\smallskip ~~~~~~~~~\texttt{READ ( 13 ) field\_char}\\ \par\smallskip ~~~~~~~~~\texttt{ENDDO}\\ ~~~~~\texttt{ENDIF}\\ \par\smallskip ~\texttt{END SUBROUTINE user\_read\_restart\_data}}; \end{tikzpicture} \end{center} \end{frame} % Folie 18 \begin{frame} \frametitle{Using the User-Interface with \texttt{mrun}} \scriptsize \begin{columns}[T] \begin{column}{1.1\textwidth} \vspace{-1mm} \textbf{Users can add their own (modified) user-interface to a PALM-run by carrying out the following steps:} \begin{enumerate} \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.:\\ \tiny \par\smallskip \quad \texttt{cd \~{ }/palm/current\underline{ }version}\\ \quad \texttt{mkdir -p USER\underline{ }CODE/example\underline{ }cbl}\\ \quad \texttt{cp trunk/SOURCE/user\underline{ }module.f90 USER\underline{ }CODE/example\underline{ }cbl/user\underline{ }module.f90}\\ \quad \texttt{cp trunk/SOURCE/user\underline{ }parin.f90\hspace{1em}USER\underline{ }CODE/example\underline{ }cbl/user\underline{ }parin.f90}\\ \quad \texttt{...} \scriptsize \vspace{-1mm} \item<3-> Set an additional path in the configuration file \texttt{.mrun.config} to allow \texttt{mrun} to find and include this file:\\ \tiny \quad \texttt{\%add\underline{ }source\underline{ }path \hspace{1em} \$base\underline{ }directory/USER\underline{ }CODE/\$fname} \scriptsize \item<4-> Modify the interface routines according to your needs. \item<5-> Start a PALM run by executing\\ \tiny \quad \texttt{mrun -d example\underline{ }cbl ...}\\ \scriptsize The files user\underline{ }*.f90 will be automatically compiled within the job / interactive run and will replace the respective PALM default user-interface files. \end{enumerate} \vspace{-2mm} \begin{itemize} \item<6-> \textbf{The modified user-interface file cannot be pre-compiled by using} \texttt{mbuild}! \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. \end{itemize} \end{column} \end{columns} \end{frame} \end{document}