source: palm/trunk/TUTORIAL/SOURCE/program_control.tex @ 1443

% $Id: program_control.tex 973 2012-08-07 16:03:47Z raasch $
\input{header_tmp.tex}
%\input{header_LECTURE.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,decorations.pathreplacing}
\def\Tiny{\fontsize{4pt}{4pt}\selectfont}

%---------- neue Pakete
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{multicol}
\usepackage{pdfcomment}

\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.eps}}

\title[Program Control by Physical Parameters]{Program Control by Physical Parameters}
\author{Siegfried Raasch}

% Notes:
% jede subsection bekommt einen punkt im menu (vertikal ausgerichtet.
% jeder frame in einer subsection bekommt einen punkt (horizontal ausgerichtet)
\begin{document}
% Folie 1
\begin{frame}
\titlepage
\end{frame}

% Folie 2
\begin{frame}
   \frametitle{Steering of PALM and Interpreting the Output}
   \begin{itemize}
      \item<1->{This section section describes how to steer the model and how to interpret the model output (\textbf{it does not explain, how to start and control model runs}).}
      \item<2->{It gives a general overview of the input and output files and explaines the contents of the most important files in some detail.}
   \end{itemize}
\end{frame}

% Folie 3
\begin{frame}
   \frametitle{PALM Input/Output Overview (I)}
   \tikzstyle{start} = [ellipse, draw, fill=green!20, font=\small]   
   \tikzstyle{yellow1} = [rectangle, draw, fill=yellow!20, text width=0.2\textwidth, font=\Tiny]
   \tikzstyle{yellow2} = [rectangle, draw, fill=yellow!20, text width=0.1\textwidth, font=\Tiny]
   \tikzstyle{yellow3} = [rectangle, draw, fill=yellow!20, text width=0.03\textwidth, font=\Tiny]
   \tikzstyle{red} = [rectangle, draw, fill=red!100, text width=0.1\textwidth, font=\Tiny]
   \tikzstyle{red2} = [rectangle, draw, fill=red!100, text width=0.03\textwidth, font=\Tiny]
   \tikzstyle{orange1} = [rectangle, draw, fill=orange!50, text width=0.1\textwidth, font=\Tiny]
   \tikzstyle{orange2} = [rectangle, draw, fill=orange!50, text width=0.11\textwidth, font=\Tiny]
   \tikzstyle{orange3} = [rectangle, draw, fill=orange!50, text width=0.03\textwidth, font=\Tiny]

   \tikzstyle{line} = [draw, -latex']
   
   \begin{tikzpicture} [auto]
    \node[start] (palm) {\textbf{PALM}}; 

    \uncover<2->{\node[yellow1] (parameterfile) [above left=1.5cm of palm] {parameter file \\ for steering};}
    \uncover<6->{\node[red] (restartdata1) [above right=1.8cm of palm] {restart data};}
    \uncover<5->{\node[red] (restartdata2) [below=4.5cm of restartdata1] {restart data};}

    \uncover<4->{
    \node[orange1] (timeseries) [below left=4.4cm of palm] {time series};
    \node[orange2] (2dsectionstime) [right=0.5cm of timeseries] {2D sections \\ time averaged};
    \node[orange2] (3ddatatime) [right=0.39cm of 2dsectionstime] {3D data \\ time averaged};

    \path<4->[line] (palm) -- (timeseries);
    \path<4->[line] (palm) -- (2dsectionstime);
    \path<4->[line] (palm) -- (3ddatatime);
    
    \node[orange1] (1dmean) [above=0.2cm of timeseries] {1D mean \\ profiles};
    \node[orange1] (2dsections) [right=0.5cm of 1dmean] {2D sections};
    \node[orange1] (3ddata) [right=0.5cm of 2dsections] {3D data};}

    \path<4->[line] (palm) -- (1dmean);
    \path<4->[line] (palm) -- (2dsections);
    \path<4->[line] (palm) -- (3ddata);

    \uncover<3->{\node[yellow2] (headerfile) [above=0.5cm of 2dsections]{header file};}
    \uncover<3->{\node[yellow1] (runcontrol) [right=0.5cm of headerfile]{run control output\\ (parameter settings + \\ timestep informations)};}
    \uncover<3->{\node[yellow2] (cpumeasure) [left=0.5cm of headerfile]{cpu\\ measurements};}

    \node (program) [right=2.8cm of palm] {program};
    \uncover<2->{\node (steeringdata) [right=0.45cm of restartdata1] {steering data};}
    \uncover<3->{\node (run) [right=2.7cm of runcontrol] {run informations};}
    \uncover<4->{\node (analysis) [right=3.8cm of 3ddata] {analysis data};}

    \uncover<7->{
    \node[yellow3] (yellow) [below=0.5 of timeseries] {};
    \node (ascii) [right=0.1cm of yellow] {ASCII};
    \node[orange3] (orange) [right=0.4cm of ascii] {};
    \node (netcdf) [right=0.1cm of orange] {netCDF};
    \node[red2] (red) [right=0.4cm of netcdf] {};
    \node (binary) [right=0.1cm of red] {binary};}

    \path<2->[line] (parameterfile) -- (palm);
    \path<3->[line] (palm) -- (cpumeasure);
    \path<3->[line] (palm) -- (headerfile);
    \path<3->[line] (palm) -- (runcontrol);
    \path<5->[line] (palm) -- (restartdata2);
    \path<6->[line] (restartdata1) -- (palm);
    \path<6->[line,dashed] (restartdata2) -- (restartdata1);    
   \end{tikzpicture}
\end{frame}

% Folie 4
\begin{frame}
   \frametitle{PALM Input/Output Overview (II)}
   \tikzstyle{start} = [ellipse, draw, fill=green!20, font=\small]   
   \tikzstyle{yellow1} = [rectangle, draw, fill=yellow!20, text width=0.2\textwidth, font=\Tiny]
   \tikzstyle{yellow2} = [rectangle, draw, fill=yellow!20, text width=0.1\textwidth, font=\Tiny]
   \tikzstyle{yellow3} = [rectangle, draw, fill=yellow!20, text width=0.03\textwidth, font=\Tiny]
   \tikzstyle{yellow4} = [rectangle, draw, fill=yellow!100, text width=1.8cm, font=\Tiny]
   \tikzstyle{red} = [rectangle, draw, fill=red!100, text width=0.1\textwidth, font=\Tiny]
   \tikzstyle{red2} = [rectangle, draw, fill=red!100, text width=0.03\textwidth, font=\Tiny]
   \tikzstyle{orange1} = [rectangle, draw, fill=orange!50, text width=0.1\textwidth, font=\Tiny]
   \tikzstyle{orange2} = [rectangle, draw, fill=orange!50, text width=0.11\textwidth, font=\Tiny]
   \tikzstyle{orange3} = [rectangle, draw, fill=orange!50, text width=0.03\textwidth, font=\Tiny]

   \tikzstyle{line} = [draw, -]
   
   \begin{tikzpicture} [auto]
    \node[start] (palm) {\textbf{PALM}}; 

    \node[yellow1] (parameterfile) [above left=1cm of palm] {parameter file \\ for steering};
    \node[red] (restartdata1) [above right=1.3cm of palm] {restart data};
    \node[red] (restartdata2) [below=2.5cm of restartdata1] {restart data};

    \node[yellow1] (runcontrol) [below=0.4cm of palm]{run control output\\ (parameter settings + \\ timestep informations)};
    \node[yellow2] (headerfile) [left=0.5cm of runcontrol]{header file};
    \node[yellow2] (cpumeasure) [left=0.5cm of headerfile]{cpu\\ measurements};

    \node[orange1] (1dmean) [below=0.3cm of cpumeasure] {1D mean \\ profiles};
    \node[orange1] (2dsections) [right=0.5cm of 1dmean] {2D sections};
    \node[orange1] (3ddata) [right=0.5cm of 2dsections] {3D data};

    \node[orange1] (timeseries) [below=0.2cm of 1dmean] {time series};
    \node[orange2] (2dsectionstime) [right=0.5cm of timeseries] {2D sections \\ time averaged};
    \node[orange2] (3ddatatime) [right=0.39cm of 2dsectionstime] {3D data \\ time averaged};

    \node (program) [right=2.8cm of palm] {program};
    \node (steeringdata) [right=0.8cm of restartdata1] {steering data};
    \node (run) [right=2.5cm of runcontrol] {run informations};
    \node (analysis) [right=3.6cm of 3ddata] {analysis data};
    
    \node[yellow3] (yellow) [below=0.3 of timeseries] {};
    \node (ascii) [right=0.1cm of yellow] {ASCII};
    \node[orange3] (orange) [right=0.4cm of ascii] {};
    \node (netcdf) [right=0.1cm of orange] {netCDF};
    \node[red2] (red) [right=0.4cm of netcdf] {};
    \node (binary) [right=0.1cm of red] {binary};

    %--------- neue Ordner
    \uncover<2->{
    \node[yellow4] (currentversion) [above=0.6cm of parameterfile] {current\_version/};
    \node[yellow4] (jobs) [right=0.3cm of currentversion] {JOBS/};
    \node[yellow4] (runidentifier) [right=0.4cm of jobs] {\textless run\_identifier \textgreater/};
    \node[yellow4] (input) [above right=1cm of runidentifier] {INPUT/};
    \node[yellow4] (monitoring) [below=0.1cm of input] {MONITORING/};
    \node[yellow4] (output) [below=0.1cm of monitoring] {OUTPUT/};
    \node[yellow4] (restart) [below=0.1cm of output] {RESTART\_DATA/};}

    \uncover<3->{\node[yellow4] (input2) [below=0.1cm of parameterfile] {INPUT/};}
    \uncover<4->{\node[yellow4] (monitoring2) [above=0.6cm of headerfile] {MONITORING/};}
    \uncover<6->{\node[yellow4] (restart2) [below=0.1cm of restartdata1] {RESTART\_DATA/};}
    \uncover<7->{\node[yellow4] (tmpdata) [below=0.1cm of restart2] {/tmp\_data\_catalog/};}
    \uncover<5->{\node[yellow4] (output2) [below=0.5cm of restartdata2] {OUTPUT/};}

    \path[line]<2-> (currentversion) -- (jobs);
    \path[line]<2-> (jobs) -- (runidentifier);
    \path[line]<2-> (runidentifier.east) -- (input.west);
    \path[line]<2-> (runidentifier.east) -- (monitoring.west);
    \path[line]<2-> (runidentifier.east) -- (output.west);
    \path[line]<2-> (runidentifier.east) -- (restart.west);

    \draw<4->[decorate,decoration={brace,raise=6pt,amplitude=9pt},thick]
       (-4.5,-0.95)--(-1,-0.95) ;
    \draw<5->[decorate,decoration={brace,mirror,raise=5pt,amplitude=6pt},thick]
       (0.45,-3)--(0.45,-1.9) ;   
   \end{tikzpicture}
\end{frame}

% Folie 5
\begin{frame}
   \frametitle{The Parameter File}
   \tikzstyle{box} = [rectangle, draw, text width=0.9\textwidth, font=\tiny]
   \tikzstyle{line} = [draw, thick, -latex']
   \footnotesize
   \begin{itemize}
      \item<1->{Physical and numerical features of a PALM run (e.g. initial and boundary conditions, numerical methods)
            are controlled by a so called \textbf{parameter file} which uses FORTRAN-NAMELIST syntax.} 
      \item<2->{General structure of a FORTRAN-NAMELIST file}
   \end{itemize}   
   \begin{tikzpicture}[auto]  
   \uncover<3->{    
      \node[box](firstbox){ \begin{tabbing}        
         \quad \&abcd \quad \=no\_of\_eggs = 100, litres\_of\_milk = 50.0, \= \\
                 \>kilos\_of\_butter = 20.0, \> /  \end{tabbing}};  
   \node[font=\tiny] (leading_blank) at (-5,0.8) {\textbf{leading blank}}; 
   \node[font=\tiny] (namelist) at (-2,0.8) {\textbf{NAMELIST group}}; 
   \node[font=\tiny] (terminating) at (3,0.8) {\textbf{terminating character}};
   \path[line] (-5,0.7) -- (-4.8,0);  
   \path[line] (-2,0.7) -- (-4,0);
   \path[line] (3,0.7) -- (0.2,-0.3);}
   \end{tikzpicture}
   \begin{itemize}
      \item<4->{This file can be read from a FORTRAN program in the following way:} 
   \end{itemize}
   \begin{tikzpicture}[auto, node distance=0] 
   \uncover<4->{     
      \node[box](secondbox){ \begin{tabbing} 
         INTEGER :: \=no\_of\_eggs = 30 \\
         REAL :: \> litres\_of\_milk = 0.0, kilos\_of\_butter, kilos\_of\_cream = 33.0 \\
         \\
         NAMELIST /abcd/ \quad no\_of\_eggs, litres\_of\_milk, kilos\_of\_butter, kilos\_of\_cream \\
         \\
         OPEN ( 1, FILE='Filename' ) \\
         \\
         READ ( 1, abcd ) \end{tabbing}};}       
   \end{tikzpicture}
   \normalsize 
\end{frame}

% Folie 6
\begin{frame}
   \frametitle{An Example of PALM - NAMELIST Input}
   \tikzstyle{box} = [rectangle, draw, text width=\textwidth, font=\tiny]
   \begin{tikzpicture}[auto, node distance=0]      
      \node[box](box){ \begin{tabbing} 
         \&inipar \=nx = 39, ny = 39, nz = 40, \\
                  \>dx = 50.0, dy = 50.0, dz = 50.0, \\
                  \\
                  \>initializing\_actions = 'set\_constant\_profiles', \\  
                  \>ug\_surface = 0.0, vg\_surface = 0.0, \\
                  \\
                  \>pt\_vertical\_gradient  \qquad = 0.0, 1.0, \\
                  \>pt\_vertical\_gradient\_level = 0.0, 800.0, \\
                  \\
                  \>surface\_heatflux = 0.1, bc\_pt\_b ='neumann', / \\
                  \\
                  \\
         \&d3par  \>end\_time = 3600.0, \\
                  \\
                  \>dt\_dopr = 900.0, averaging\_interval\_pr = 600.0, \\
                  \>data\_output\_pr = 'pt', 'u', 'v', / \\ \end{tabbing}};       
   \end{tikzpicture}
   \footnotesize
   \begin{itemize}
      \item<2->{There are two NAMELIST groups ({\tt \&inipar} and {\tt \&d3par}).} 
      \item<3->{Assignments to parameters in {\tt\&inipar} are ignored within restart runs \\
            (exception: {\tt initializing\_actions} = {\tt'read\_restart\_data'} is obligatory for restart runs).}
      \item<4->{Values of {\tt \&d3par} parameters can be changed for restart runs.}
   \end{itemize}
\end{frame}

% Folie 7
\begin{frame}
   \frametitle{The Run Control File}
   \scriptsize
   \begin{itemize}
      \item<1->{For initial runs, the parameter settings and many additional informations about the run (header informations) are printed at the beginning of this file.}
      \item<2->{The parameter settings are followed by values of specific model variables for certain timesteps (one line for each timestep, the output intervall can be
            controlled by run parameter {\tt dt\_run\_control}).}
   \end{itemize}
   \onslide<3->{\textbf{Contents of this timestep output should be carefully checked after each run, because it allows a first control, if the model had run correctly, or if any
      errors have occurred!}}
   \par\bigskip
   \includegraphics[width=1.08\textwidth]{program_control_figures/run_control_file.png}
   \normalsize
\end{frame}

% Folie 8
\begin{frame}
   \frametitle{The Header File}
   \scriptsize
   \begin{itemize}
      \item{The header file contains nearly the same informations as the header of the run control file of the initial run.} 
      \item<2->{It is generated for \textbf{every} run (initial run as well as restart runs).}
      \item<3->{It is created at the beginning \textbf{and} at the end of a run (overwrites the file created at beginning).}
      \item<4->{Only at the end, cpu time information is included!}
   \end{itemize}
   \begin{center}
   \includegraphics[width=0.9\textwidth]{program_control_figures/header_file.png}
   \end{center}
   \normalsize
\end{frame}

% Folie 9
\begin{frame}
   \frametitle{CPU Measurements File}
   \begin{columns}[c]
   \column{0.42\textwidth}
      \scriptsize
      \begin{itemize}
         \item{Contains informations about the CPU requirements of single parts of the program.}
         \item<2->{It should be inspected regularly in order to find out, if the code is still well optimized (e.g. load balance).} 
         \item<3->{Prognostic-equations and pressure solver ({\tt pres}) should be the main consumer.}
         \item<4->{For larger grids ($400^3$ points), {\tt pres} may need up to 50\% of the total time.}
         \item<5->{Time needed for communication (sum of {\tt exchange\_horiz}({\tt \_2d}) and {\tt mpi\_alltoall}) should not exceed about 10-15\% of the total time.}
      \end{itemize}
      \normalsize
   \column{0.58\textwidth}
      \includegraphics[width=1.1\textwidth]{program_control_figures/cpu_measurements_file.png}
   \end{columns}
\end{frame}

% Folie 10
\begin{frame}
   \frametitle{Other Files}
   \small
   \begin{itemize}
      \item<1->{Data output files (1D profiles and timeseries, 2D cross sections, 3D volume data) are by default in \textbf{netCDF} format which is suitable to be processed by
            public domain graphics software like \textbf{ncview}, \textbf{ferret}, \textbf{ncl} (used by PALM group), \textbf{IDL}, etc. \\
            \par\bigskip
            For a first look, {\tt ncview} is a convenient tool.}
      \item<2->{{\tt ncdump} can be used to display the netCDF file contents in ASCII format ({\tt ncdump -c} displays only header informations).}
      \item<3->{The simple viewer for netCDF-data - {\tt ncview} - as well as ncl graphic software is available on the IMUK-cluster.}
   \end{itemize}
\end{frame}

% Folie 11
\begin{frame}
   \frametitle{Steering by Unix Environment Variables}
   \scriptsize
   Most features of PALM are controlled by the parameter file but a few are exclusively controlled by unix environment variables. The most important one is  {\tt write\_binary}. \\
   \par\bigskip
   Setting \\
   \par\medskip
   {\centering \texttt{ write\_binary = true} \\
   \par\medskip
   within the shell causes PALM to write binary data for restart runs at the end of a run.}
   \par\bigskip
   \uncover<2->{Setting of these environment variables is automatically done by  {\tt mrun}. It generates a local file (named {\tt ENVPAR}) in FORTRAN-NAMELIST-format, which is then
   read by PALM. This file includes the following variables:} \\
   \par\bigskip
   \tiny
   \uncover<3->{
   \begin{tabular}{|p{3cm}|p{4cm}|p{3cm}|} \hline
      \textbf{Variable}                 & \textbf{Meaning} & \textbf{Value set by {\tt mrun}-option} \\
      \hline
      {\tt host}                        & host identifier that mrun is using for the host on which the job is running & {\tt -h}    \\
      {\tt maximum\_cpu\_time\_allowed} & cpu time allowed for the job                                                & {\tt -t}    \\
      {\tt run\_identifier}             & identification string for the run    & {\tt -d}    \\
      {\tt tasks\_per\_node}            & number of MPI tasks to be started on each node     & {\tt -T}     \\
      {\tt write\_binary}               & switch for writing binary data to be used for restart runs     & {\tt -r} (+setting in configuration file {\tt .mrun.config)}  \\
      \hline
   \end{tabular}}
   \normalsize
\end{frame}

% Folie 12
\begin{frame}
   \frametitle{PALM / netCDF Documentation}
   \begin{itemize}
      \item<1->{A detailed description of how to use PALM and a complete list of steering parameters and their meaning can be found on the PALM-server: \\
            \par\bigskip
            \textbf{http://palm.muk.uni-hannover.de/wiki/doc/toc}}
      \par\bigskip
      \item<2->{General information about the netCDF data format can be found under \\
            \par\bigskip
            \textbf{http://www.unidata.ucar.edu/software/netcdf/}}
   \end{itemize}
\end{frame}

\end{document}