\chapter{Introduction}

This guide is intended for people interested in developing and enhancing
the \PR package. It describes the \fort programming style used in \PR and
explain the underlying principles of {\em object-based} and module-oriented
programming followed throughout our implementation.  The aim is to help the
developer to understand the general philosophy followed during our project
and easily improve upon the existing code.

\section{About \fort in \PR}

Release \PR differs significantly from the previous ones (versions 3 and
4.0).  The most important change is that the package is undergoing a complete
refactoring to be written in \fort. This will require in the next future a
radical change from the previous \oldfort, a procedural programming language,
to an {\em object-based/oriented} programming protocol.

It is our opinion that \oldfort is no longer the right tool to deal with
such a large project, especially when large type of data sets need to be
managed across the whole package, and the model itself needs a clean and
convenient infrastructure to be coupled with a broad spectrum of complementary
physics models to become part of more complete earth climate modelling
framework. The main weakness of \oldfort is the lack
of any explicit mechanism to express the dependencies among different data
structures and procedures. This makes the development process hard and
difficult: any new change in the code requires an analysis of the involved
data across the whole code and, in the case of \oldfort, this is done
necessarily by analyzing many source files.  This procedure could be very
error prone, especially for developers not mastering all the data of the
entire software project.  \par On the contrary \fort is a modern
programming language with features that support new important programming
concepts, including some of those used in object oriented (OO)
programming. \fort is moreover backward compatible with \oldfort: it was
therefore possible to introduce \fort features into the code in a
incremental fashion, and a lot of work already done could be easily
incorporated.\par
\PR represents now a first release towards a full development along the 
guidelines of modular and OO programming style.  The transition from
procedural to the modular paradigm and later object -base paradigm is not
yet completed in the present release.  At this stage, after having analyzed
the old data structures and their interdependencies, we have built a first
hierarchy of modules containing the relevant data structures. In this way
the relationships amongst data are made explicit. Furthermore in some
cases we have included directly in the module itself the subroutines acting
on the data : this is the concept of classes of methods on OO programming
and now data and routines acting on them are tightly linked
together. Therefore any modification of the code becomes extremely
localized, and adding new features needs a much simpler
intervention than in the past. For example, implementing a new algorithm
for dust requires just to change a single \fort module. \par
To summarize it has to be stressed that now in \fort the building blocks
of the program are modules, not subroutines, and to modify the code one has
to understand the modules hierarchy build up. The general description of
the latter is presented in the following sections.

\section{Object-oriented programming in \fort}


Learning \fort is easy for \oldfort  programmers
\cite{Brainerd,Metcalf,Kerrigan}. A more difficult task is ``thinking'' in
terms of {\em objects} and {\em methods} \cite{Stroustrup}, even though
\fort is not really an object-oriented, but only an object-based, language.\par
There is an excellent web site \cite{oof90_web} where OO techniques used in the \PR project are
clearly explained and examples are provided. We strongly recommend it to
interested  people.


\chapter{The \PR programming style}

The programming style of \PR is intended to be as uniform as possible.
Potential contributors to the code are kindly requested to follow the stylistic convention.

\section{Programming Language}

The general programming language is \fort. 
Some \oldfort routines are still present in the
package and they should be regarded as temporary, and due to migration
from version 3.0.
\C routines are permissible, provided they are Fortran compatible.
File names extensions are:

 \begin{itemize}
 \item 
 \verb=.F90= : for f90 free format code, containing preprocessing directives
  to be analyzed by fortran preprocessor
 \item
 \verb=.f90= : for f90 free format code not to be preprocessed.
 \item
 \verb=.c= : for C code 
 \end{itemize}

Compilation is achieved with a hierarchy of Makefiles
 \begin{itemize}
  \item
    \verb=Makefile= : the Makefile with general and architecture-independent 
                      rules
  \item
    \verb=Makefile.={\it arch} : the architecture dependent Makefiles
  \end{itemize}
Two distinct rules are given in the Makefile:

 \begin{itemize}
 \item
  \verb=.F90.o=  using the macros {\macro \$(F90)} and 
{\macro \$(FCFLAGS)} for related flags. The files are preprocessed.
 \item
  \verb=.f90.o= rule, using the macros {\macro \$(F90)} for compiler and 
{\macro \$(FCFLAGS)} for related flags.
 \end{itemize}

Modules have always the extension \verb=.[fF]90=. and should start with \verb=\mod_=.
Avoid uppercase letters, especially for modules, since module names
are converted to lowercase by the compiler.
 
\subsection{ Banned \oldfort language features:}

 \begin{itemize}
 \item {\tt common}, instead use modules;
 \item {\tt include}, instead use modules and \verb=#include=;
 \item {\tt implicit double precision}, instead use {\tt implicit none});
 \item  Obsolescent \oldfort features, e.g. see Chapt.1 of \cite{Kerrigan}.;
 \item \oldfort notation, such as \verb=real*8=, etc.;
 \item  Non-standard \oldfort integer pointers, instead use allocatable
   arrays, or \fort pointers;
 \item  Avoid vendor extensions that diminish portability.
 \end{itemize}


\section{Target Computers}

\PR is primarily developed on Linux Cluster in both its serial and parallel versions using the MPI communication library. 

During its developing phase the code is compiled using three different suite of compilers:

\begin{itemize}
\item Intel suite compiler (from 10.1 to 12.0 )
\item gfortran compiler  version 4.4 on 
\item Pgi suite of compiler (version 9.03 on) 
\end{itemize}

The code is, however, developed having in mind portability (see later for a detailed
discussion about this issue) and it has also been carefully tested (parallel version) on AIX SP6 IBM platform with xlf  compiler.

\section{Module Template}

A \verb=module= is the basic unit of the code, and any function or subroutine is
wrapped in a \verb=module=. A \verb=module= contains data to be shared with
other \PR modules and data internal to the \verb=module=. The \fort attribute
\verb=private= should be placed right after the \verb=use= lines in the
\verb=module= code. Any items, be data, function or subroutine to be accessed
from other modules or the Main program is to be explicitly given the 
\verb=public= attribute.

Two default subroutines should be present in a \verb=module=:

\begin{enumerate}
\item \verb=init_mod_modname= : Allocates dynamic space in heap and set up any
internal control flag.
\item \verb=release_mod_modname= : Deallocates resources and cleanup
\end{enumerate}

Any number of function and subroutines can be present in a \verb=module=
The variables in the subroutine arguments are specified in the order:

\begin{enumerate}
\item input arguments to subroutine
\item output arguments from subroutine
\item logical flags to control internal branching
\end{enumerate}

This method is sometimes used quite liberally. 
\PR enforces for a safer a cleaner programming usage of the \fort
attribute \verb=intent(in/out/inout)= for subroutine arguments.  
An example of a module with a defined subroutine is given in the following
example:

\lstinputlisting[language=Fortran]{mod_template.f90}

\section{FORTRAN Parameters}
All parameters defined by the \fort parameter statements are specified
in modules and described in one or more comment cards.

\section{Arithmetic Precision}
All real variables and parameters are specified in 64-bit precision 
(i.e. real(kind=8)). 
The future release of \PR will count on \fort features in order to set its
proper defined precision. 

\section{Other Issues} 

\subsection{\fort/\oldfort\ (in)compatibility}

To achieve language compatibility the developer should keep in mind that
using arrays as dummy arguments can slow down the performances
dramatically. Beware of passing \fort\ array descriptors (e.g., {\tt
a(:,2:18:2)}) to \oldfort\ ssubroutines. This forces the \fort compiler to
make local copies of the array in order to make it contiguous, whereas in
\fort contiguity is not required with a net loss of speed.

\chapter{ Useful (?) Tips }

\section{How to debug the code }

\PR provides a Debugging facility to help developers and users.
In order to activate the debugging facility, the code must be compiled
with the macro \verb=DEBUG= enabled. 
At runtime the code produces different files containing information
about different processors. File names are \verb=DEBUG_0= for processors 0 
or for a serial run, and \verb=fort.={\it nn} for parallel runs, 
where {\it nn} is the processor number, numbered from 0 to N-1.

The debug level goes from 0 (very basic information) to 6 (detailed
information: beware the \verb=DEBUG_.={\it nn} files can be huge).

The default behaviour of the code is DEBUG disabled and debug\_level
variable equal to 0. DEBUG\_* files report quite detailed information about
the initialization phase and then silence during the iteration steps. 
We strongly recommend  users/developers to run with this default,
especially when they start to simulate new systems.

In the code all the debug section are inserted within
\begin{verbatim}
#ifdef DEBUG
 ! Something to be done only in debug mode
#endif
\end{verbatim}
