source: palm/trunk/TUTORIAL/SOURCE/ncl.tex @ 1809

%$Id: ncl.tex 1649 2015-09-15 16:34:42Z raasch $
\input{header_tmp.tex}
%\input{header_lectures.tex}

\usepackage[utf8]{inputenc}
\usepackage{ngerman}
\usepackage{pgf}
\usepackage{subfigure}
\usepackage{units}
\usepackage{multimedia}
\usepackage{hyperref}
\newcommand{\event}[1]{\newcommand{\eventname}{#1}}
\usepackage{xmpmulti}
\usepackage{tikz}
\usetikzlibrary{shapes,arrows,positioning}
\usetikzlibrary{calc}                             %neues paket
\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{Institute of Meteorology and Climatology, Leibniz Universit{\"a}t Hannover}
\selectlanguage{english}
\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[Introduction to NCL]{Introduction to NCL}
\author{PALM group}

\begin{document}

% Folie 1
\begin{frame}
\titlepage
\end{frame}

\section{Introduction to NCL}
\subsection{Introduction to NCL}

% Folie 2
\begin{frame}
   \frametitle{Visualization of PALM Output Data}
   \small
   \begin{itemize}     
           \item<1-> There are several ways how you can visualize netCDF data
           \item<1-> If you are lacking experience in the visualization of netCDF data or if you have not yet found your favourite way how to visualize netCDF data, here is one recommendation:
           
           \begin{center}NCL -- The \textbf{N}CAR \textbf{C}ommand \textbf{L}anguage\end{center}
      \item<2-> Developed at the NCAR (and continuously updated)
      \item<2-> Detailed information is available under http://www.ncl.ucar.edu
      \item<3-> With the information revealed in this talk you will be able to visualize the output of this week's simulations
   \end{itemize}   
\end{frame}

% Folie 3
\begin{frame}
   \frametitle{What is NCL and Which are its Advantages? (I)}
   \small
   \begin{itemize}     
      \item<1-> Interpreted language designed specifically for scientific 
                data processing and visualization, freely available
      \item<2-> Portable: it is running on many different operating systems
                including Linux, Mac OS X, Windows, ...
      \item<3-> It's a powerful tool for file input and output, visualization and data analysis $\rightarrow$ integrated processing environment
      \vspace{-0.2cm}
                  \begin{center}
                   \onslide<3-> \includegraphics[scale=0.315]{ncl_figures/ncl.png}
                   \end{center}
      \end{itemize}  

   
\end{frame}

% Folie 4
\begin{frame}
   \frametitle{What is NCL and Which are its Advantages? (II)}
   \small
   \begin{itemize}     
           \item<1-> Supports calling of C and FORTRAN routines
           \item<1-> Over 600 functions and procedures for visualization and 
                     data analysis are provided with NCL
           \item<2-> \textbf{Interactive mode}: \texttt{\$ ncl}\\          
      \hspace{2.95cm}\texttt{ncl 0> ...}
      \item<2-> Each line is interpreted as it is entered
      \item<3-> \textbf{Batch mode}: \texttt{\$ ncl ncl\underline{ }script.ncl}
      \item<3-> Interpreter of complete scripts, variables within the NCL script can be steered by providing additional parameters with the NCL call:\\
      \texttt{\$ ncl ncl\underline{ }script.ncl parameter1=value ...}
       \item<4-> Since NCL is an interpreted language, \textbf{the excessive usage of loops seriously decrease the performance of NCL!}
   \end{itemize}  

\end{frame}

% Folie 5
\begin{frame}
   \frametitle{What is NCL and Which are its Advantages? (III)}

   \begin{itemize}     
           \item<1-> Complete Programming Language
           \begin{itemize}   
              \footnotesize
              \item<1-> data types (float, double, integer, logical, ...)
              \item<1-> variables
              \item<1-> operators
              \item<1-> expressions
              \item<1-> loops
              \item<1-> functions and procedures (e.g., \texttt{dim\_stat4(data\_array)})
      \end{itemize}  
           \item<2-> Features
           \begin{itemize}   
              \footnotesize
              \item<2-> manipulate meta data
              \item<2-> import data in a variety of formats (netCDF, ASCII, ...)
              \item<2-> array syntax / operations
              \item<2-> can use user FORTRAN/C codes and commercial libraries
              \item<2-> most functions/procedures ignore missing data
      \end{itemize}  
   \end{itemize}  

\end{frame}

% Folie 6
\begin{frame}
   \frametitle{How to Install NCL (Under Linux) (I)?}
   \small
   \begin{itemize}     
      \item<1-> Detailed information is available under:\\
                \underline{http://www.ncl.ucar.edu/Download/index.shtml}
      \item<1-> For downloading, request an Earth System Grid account:\\
                \underline{http://www.earthsystemgrid.org/}
      \item<2-> Download the appropriate binaries e.g. \texttt{A.tar.gz} 
                for your system e.g. to \texttt{\$HOME}
      \item<2-> \texttt{\% gunzip \$HOME/A.tar.gz}
      \item<2-> \texttt{\% mkdir -p /usr/local}\\
      \texttt{\% cd /usr/local}\\
      \texttt{\% tar -xvf \$HOME/A.tar}
   \end{itemize}  

\end{frame}

% Folie 7
\begin{frame}
   \frametitle{How to Install NCL (Under Linux) (II)?}
   \footnotesize 
   \begin{itemize}     
      \item<1-> Set the \texttt{NCARG\underline{ }ROOT} environment variable and
                your search path to where NCL/NCARG resides:\\
                csh: \texttt{setenv NCARG\underline{ }ROOT /usr/local/}\\
                \hspace{1.6em} \texttt{setenv PATH /usr/local/bin:\$PATH}\\
                bash/ksh: \texttt{export NCARG\underline{ }ROOT=/usr/local/}\\
                \hspace{4.1em} \texttt{export PATH=/usr/local/bin:\$PATH}\\
      \vspace{3mm}
      \item<2-> Set the DISPLAY environment variable to indicate where to 
                display graphics (as for any X11 Windows application that you 
                run):\\
                ksh: \texttt{export DISPLAY=localhost:13.0}, \\
                or use \texttt{ssh -X} to tunnel X-communication
      \vspace{3mm}
      \item<3-> Test your NCL installation:\\
                \quad \texttt{\% ng4ex gsun01n}\\
                The NCL script gsun01n.ncl is copied to your working directory and 
                executed by NCL. An X11 window should pop up.
   \end{itemize}  

\end{frame}

% Folie 8
\begin{frame}
   \frametitle{NCL Scripts Delivered with PALM (I)}
   \footnotesize 
   \begin{itemize}     
      \item<1-> Together with the PALM installation you have also received four NCL scripts, a configuration file and a manual; they can be found in the directory:\\
                \texttt{\$HOME/palm/current\underline{ }version/trunk/SCRIPTS/NCL/}
      \item<2-> All standard netCDF data output of PALM can be visualized by one
                of the scripts:
                \begin{itemize}
                   \scriptsize
                   \item[-]<2-> \texttt{cross\underline{ }sections.ncl} 
                                (contour or vector plots from 2D/3D data)
                   \item[-]<2-> \texttt{profiles.ncl} (profiles from profiles/3D data)
                   \item[-]<2-> \texttt{timeseries.ncl} (time series data)
                   \item[-]<2-> \texttt{spectra.ncl} (spectra data)
                \end{itemize}  
      \item<3-> To run these NCL scripts you can use the shell script 
                \texttt{palmplot} which can be found in the directory:\\
                \texttt{\$HOME/palm/current\underline{ }version/trunk/SCRIPTS}
      \item<4-> The output of the plots can be changed with several parameters;
                these parameters can be either written in the prompt 
                (when calling the shell script \texttt{palmplot}) or set 
                within the configuration file \texttt{.ncl.config}
   \end{itemize}  

\end{frame}

% Folie 9
\begin{frame}
   \frametitle{NCL Scripts Delivered with PALM (II)}

   Using \texttt{.ncl.config}:
   \small
   \begin{itemize}     
      \item<1-> Please create a personal configuration file by copying 
                   the default configuration file 
                   \texttt{.ncl.config.default} to the PALM working 
                   directory \texttt{\$HOME/palm/current\underline{ }version}
                   and naming it \texttt{.ncl.config}
      \item<2-> \texttt{.ncl.config} is used by NCL directly, thus the 
                   parameters have to be written according to the rules of the 
                   scripting language NCL
      \item<3-> The configuration file contains all steering parameters with 
                   a short description and can be adjusted to personal needs
   \end{itemize}  

\end{frame}

% Folie 10
\begin{frame}
   \frametitle{NCL Scripts Delivered with PALM (III)}

   Using \texttt{palmplot} (I)
   \footnotesize
   \begin{itemize}     
      \item<1-> The shell script is used as follows:\\
                   \texttt{palmplot <plot\underline{ }identifier>}
      \item<1-> \texttt{<plot\underline{ }identifier>} has to be \texttt{xy},
                   \texttt{xz}, \texttt{yz}, \texttt{pr}, \texttt{sp} or 
                   \texttt{ts} depending on the data to be plotted
   \end{itemize}     
   \vspace{3mm}
   \onslide<2->
   \begin{center}
      \begin{tabular}{ccc}
         \textbf{plot\underline{ }identifier} & \textbf{data used} & \textbf{ncl script}\\
         xy & xy or 3D data & cross\underline{ }sections.ncl\\
         xz & xz or 3D data & cross\underline{ }sections.ncl\\
         yz & yz or 3D data & cross\underline{ }sections.ncl\\
         pr & profile or 3D data & profiles.ncl\\
         sp & spectra data & spectra.ncl\\
         ts & time series data & timeseries.ncl\\ 
   \end{tabular}
   \end{center}

\end{frame}

% Folie 11
\begin{frame}
   \frametitle{NCL Scripts Delivered with PALM (IV)}

   Using \texttt{palmplot} (II)
   \footnotesize
   \begin{itemize}     
      \item<1-> To change the output of the plot you can also use the prompt:\\
                   \scriptsize 
                   \texttt{palmplot \textbf{plot\underline{ }identifier} 
                   parameter=value parameter='string' ...} 
      \footnotesize \\
      \vspace{2mm}
      \item<2-> A list of all available parameters can be found in the 
                   configuration file \texttt{.ncl.config} or in the 
                   documentation:\\
                   \uncover<3->{\texttt{http://palm.muk.uni-hannover.de/trac/wiki/doc/app/nclparlist}}\\
      \vspace{2mm}
      \item<4-> Parameters specified in the prompt override parameters given
                   in the configuration file\\
      \vspace{2mm}
      \item<5-> String parameters which can contain lists (\texttt{var}, 
                   \texttt{c\underline{ }var}, \texttt{vec1}, \texttt{vec2}, 
                   \texttt{plotvec}) have to be set in single quotes and the 
                   list itself has to be separated by blanks, e.g. 
                   \texttt{var='pt u w'}\\
      \vspace{2mm}
      \item<6-> A short introduction for using the shell script is given by 
                   typing\\
                   \texttt{palmplot ?}
   \end{itemize}     

\end{frame}

% Folie 12
\begin{frame}
   \frametitle{Application Example: Visualization of the Output of the Example 
               Run (example\underline{ }cbl) (I)}
   \small
   \begin{itemize}     
      \item<1-> Starting the example run with the command\\
                \vspace{2mm}
                \hspace{0.5cm}\texttt{mrun -d example\underline{ }cbl ... -r
                        'd3\# pr\# ts\# xy\# xz\#'}\\
                \vspace{2mm}
                results in the following output files
                
                \hspace{0.5cm}\texttt{example\underline{ }cbl\underline{ }pr.nc}, \texttt{example\underline{ }cbl\underline{ }xy.nc},\\
                 \hspace{0.5cm}\texttt{example\underline{ }cbl\underline{ }xz.nc}, \texttt{example\underline{ }cbl\underline{ }ts.nc}
                
                located in
                
                \hspace{0.5cm}\texttt{\$HOME/palm/current\underline{ }version/JOBS/example\underline{ }cbl/OUTPUT/}

                
      \item<2-> Example: Visualization of time series data\\
                \vspace{2mm}
       \item<3-> Goal: Output the eps-file \texttt{timeseries.eps} (by default the
                plot would be output to an X11 window)
   \end{itemize}     

\end{frame}

% Folie 13
\begin{frame}
   \frametitle{Application Example: Visualization of the Output of the Example 
               Run (example\underline{ }cbl) (II)}
   \small
   \begin{itemize}     
      \item<1-> In order to reach the goal you can either ...
      \item<1-> ... change to the directory\\
                \texttt{\$HOME/palm/current\underline{ }version/JOBS/example\underline{ }cbl/OUTPUT/}\\
                and use the shell script with the command:\\
                \hspace{0.5cm}\texttt{palmplot ts file\underline{ }1=example\underline{ }cbl\underline{ }ts.nc format\underline{ }out=eps}\\ 
                \hspace{0.5cm}\texttt{file\underline{ }out=timeseries}\\
                Thus, the script \texttt{timeseries.ncl} is called and some of the parameters in the configuration file \texttt{.ncl.config} are directly set by specifying the related parameters in the command line, e.\,g.,\\
                \onslide<2-> \hspace{0.5cm}\texttt{file\underline{ }1 = <netCDF file> file\underline{ }out = <output file>}
   \end{itemize}     

\end{frame}

% Folie 14
\begin{frame}
   \frametitle{Application Example: Visualization of the Output of the Example 
               Run (example\underline{ }cbl) (III)}
   \footnotesize
   \begin{itemize}
   \item<1-> ... or you can modify the configuration file \texttt{.ncl.config}, e.\,g.,\\
   \vspace{2mm}
   \texttt{if(.not. isvar(\dq file\underline{ }1\dq))then}\\
   \quad \quad \texttt{file\underline{ }1 = \dq File in\dq}\\
   \texttt{end if}\\
   \vspace{2mm}
   \onslide<2-> has to be changed to\\
   \vspace{2mm}
\texttt{if(.not. isvar(\dq file\underline{ }1\dq))then}\\
   \quad \quad \texttt{file\underline{ }1 = \dq \$HOME/palm/current\underline{ }version/JOBS/...}\\
   \hspace{+2.3cm}\texttt{...example\underline{ }cbl/OUTPUT/example\underline{ }cbl\underline{ }ts.nc\dq}\\
   \texttt{end if}
\end{itemize}
\end{frame}

% Folie 15
\begin{frame}
   \frametitle{Application Example: Visualization of the Output of the Example 
               Run (example\underline{ }cbl) (IV)}
   \footnotesize
   \begin{itemize}
      \item<1-> Both ways will create a new file called \texttt{timeseries.eps} 
                in the directory\\
               \texttt{\$HOME/palm/current\underline{ }version/JOBS/example\underline{ }cbl/OUTPUT/}
   \end{itemize}
   \centering
   \onslide<2->\includegraphics[scale=0.23]{ncl_figures/vis1.png}
   
\end{frame}

% Folie 16
\begin{frame}
   \frametitle{Application Example: Visualization of the Output of the Example 
               Run (example\underline{ }cbl) (V)}
   \footnotesize
   \begin{itemize}
      \item<1-> If you only want to get the plot of the time series of just one variable, e.\,g., the maximum of the velocity component $u$, you can add the command line parameter \texttt{var='umax'} or modify the configuration file respectively, e.\,g.,\\
      \vspace{2mm}
      \texttt{if(.not. isvar(\dq var\dq ))then}\\
      \quad \quad \texttt{var = \dq ,umax,\dq }\\        
      \texttt{end if}
   \end{itemize}
   \vspace{+0.2cm}
   \centering
   \onslide<2->\includegraphics[scale=0.3]{ncl_figures/vis2.png}
   
\end{frame}

% Folie 17
\begin{frame}[t]
   \tikzstyle{plain} = [rectangle, text width=0.27\textwidth, font=\small]
   \frametitle{Application Example: Visualization of the Output of the Example 
               Run (example\underline{ }cbl) (VI)}
   %\footnotesize
   \begin{itemize}
   \item Plot profiles with the command\\
   \quad \texttt{palmplot pr}\\
   \quad \texttt{file\underline{ }1=example\underline{ }cbl\underline{ }pr.nc}
   \item Profiles of same dimension are\\ 
            plotted together, e.\,g., total, \\
            resolved and sub-grid scale \\
            temperature flux (default)
    \item If you add the parameter \\
            \texttt{var='all'} to the command,\\
            all profiles are plotted separately 
   \end{itemize}
   \begin{tikzpicture}[remember picture, overlay]
      \node at (current page.north west){%
      \begin{tikzpicture}[overlay]
         \node[plain,anchor=west] at (72mm,-51.5mm) 
              {\includegraphics[scale=0.32]{ncl_figures/vis3.png}};
      \end{tikzpicture}
      };
   \end{tikzpicture}
   
\end{frame}

% Folie 18
\begin{frame}
   \frametitle{More Comments}
   \footnotesize
   \begin{itemize}     
      \item<1-> The other NCL scripts delivered with PALM can be used in 
                a similar way, however the parameters that can be specified 
                differ from script to script
      \item<2-> There are plenty of parameters for each script. Please have a 
                look to the NCL documentation\\
                
                \quad \texttt{http://palm.muk.uni-hannover.de/trac/wiki/doc/app/nclparlist}\\
                
                for detailed information 
      \item<3-> If one of the programs aborts and there is no comment, 
                check the configuration file! The scripts should not abort with
                default values. Be sure to use the right data type 
                (e.\,g., \texttt{integer = 2}, \texttt{float = 2.0}, \texttt{double = 2.0d}, 
                \texttt{string = \dq name\dq})!
   \end{itemize}   
\end{frame}








\end{document}