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

%$Id: ncl.tex 1515 2015-01-02 11:35:51Z keck $
\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{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{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[Introduction to NCL]{Introduction to NCL}
\author{Siegfried Raasch}

\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:
      \item<2-> NCL – The \textbf{N}CAR \textbf{C}ommand \textbf{L}anguage
      \item<2-> Developed by the Computational \& Information Systems Laboratory at the NCAR (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 AIX, Linux, MacOSX, Cygwin/Windows
      \item<3-> It's a powerful tool for file input and output, visualization 
                and data analysis (but please \textbf{avoid the excessive usage 
                of loops}, as NCL is an interpreted language) $\rightarrow$ 
                integrated processing environment
   \end{itemize}  
   \centering
   \onslide<3-> \includegraphics[scale=0.28]{ncl_figures/ncl.png}
   
\end{frame}

% Folie 4
\begin{frame}
   \frametitle{What is NCL and Which are its Advantages? (II)}
   \small
   \begin{itemize}     
           \item<1-> Supports calling C and FORTRAN extended routines
           \item<1-> Over 600 functions and procedures for visualization and 
                     data analysis are provided with NCL
           \item<2-> Interactive mode: \texttt{\$ ncl}\\
      \texttt{ncl 0>}
      \item<3-> each line is interpreted as it is entered
      \item<4-> Batch mode: \texttt{\$ ncl ncl\underline{ }script.ncl}\\
      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}
      \texttt{'parameter2=\dq string\dq ' ...}
   \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
              \item<1-> variables
              \item<1-> operators
              \item<1-> expressions
              \item<1-> loops
              \item<1-> functions/procedures/graphics
      \end{itemize}  
           \item<2-> Features
           \begin{itemize}   
              \footnotesize
              \item<2-> query / manipulate meta data
              \item<2-> import data in a variety of formats
              \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-> 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}\\
      \quad \texttt{\% cd /usr/local}\\
      \quad \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\\
                e.g. 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 gsun01}\\
                NCL script gsun01n.ncl is copied to your working directory and 
                run through 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} 
                                (2D/3D data, e.g. contour or vector plots)
                   \item[-]<2-> \texttt{profiles.ncl} (profile 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{tabular}{ccc}
         \textbf{plot\underline{ }identifier} & \textbf{data used} & \textbf{ncl script}\\
         xy & instantaneous or time-averaged xy or 3D data & cross\underline{ }sections.ncl\\
         xz & instantaneous or time-averaged xz or 3D data & cross\underline{ }sections.ncl\\
         yz & instantaneous or time-averaged 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{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:\\
                   \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/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}
                \texttt{mrun -d example\underline{ }cbl ... -r
                        'd3\# pr\# ts\# xy\# xz\#'}\\
                \vspace{2mm}
                results in the following output files in\\
                \vspace{2mm}
                \texttt{\$HOME/palm/current\underline{ }version/JOBS/example\underline{ }cbl/OUTPUT/}:\\
                \texttt{example\underline{ }cbl\underline{ }pr.nc}, \texttt{example\underline{ }cbl\underline{ }xy.nc}, \texttt{example\underline{ }cbl\underline{ }xz.nc},\\
                \texttt{example\underline{ }cbl\underline{ }ts.nc}
      \item<2-> Example: Visualization of the time series data\\
                \vspace{2mm}
                Goal: Output as 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\\
                \vspace{2mm}
                \texttt{palmplot ts file\underline{ }1=example\underline{ }cbl\underline{ }ts.nc format\underline{ }out=eps file\underline{ }out=timeseries}\\
                \vspace{2mm}
                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,\\
                \vspace{2mm}
                \onslide<2-> e.g. \texttt{file\underline{ }1 = <netCDF file>} 
                \textbf{(Note: the input file has always to be specified!)}, \texttt{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
   ... 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/example\underline{ }cbl/OUTPUT/example\underline{ }cbl\underline{ }ts.nc\dq}\\
   \texttt{end if}

\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.25]{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 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}
   \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
   Plot profiles with the command\\
   \quad \texttt{palmplot pr file\underline{ }1=example\underline{ }cbl\underline{ }pr.nc}\\
   \vspace{3mm}
   Profiles of same dimension are plotted\\
   together, e.g. total, resolved and\\
   subgridscale temperature flux (default)\\
   \vspace{3mm}
   (This composition is written to the\\
   NetCDF header by the \texttt{d3par}\\
   parameter \texttt{cross\underline{ }profiles})\\
   \vspace{3mm}
   If you add the parameter var=all to\\
   the command, all profiles will be plotted\\
   separately 
   \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}
   \small
   \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 
                (\texttt{http://palm.muk.uni-hannover.de/wiki/doc/app/nclparlist})
                for detailed information 
      \item<3-> If one of the program aborts and there is no comment, 
                check the configuration file - the scripts should not abort with
                the default values. Be sure to use the right data type 
                (e.g.: integer = 2; float = 2.0; double = 2.0d; 
                string = \dq name\dq )  
   \end{itemize}   
\end{frame}








\end{document}