%
% This file is part of ICTP RegCM model.
% Copyright (C) 2011 ICTP Trieste
% See the file COPYING for copying conditions.
%

We will in this chapter go through a sample session in using the model with
a sample configuration file prepared for this task.

\section{Setting up the run environment}

The model executables prepared in chapter \ref{install} are waiting for us to
use them. So let's give them a chance.

The model test run proposed here requires around 100Mb of disk space to store
the DOMAIN and ICBC in input and the output files. We will assume here that you,
the user, have already established a convenient directory on a disk partition
with enough space identified in the following discussion with \verb=$REGCM_RUN=

We will setup in this directory a standard environment where the model can be
executed for the purpose of learning how to use it.

\begin{Verbatim}
$> cd $REGCM_RUN
$> mkdir input output
$> ln -sf $REGCM_ROOT/bin .
$> cp $REGCM_ROOT/Testing/test_001.in .
$> cd $REGCM_RUN
\end{Verbatim}

Now we are ready to modify the input namelist file to reflect this directory
layout. A namelist file in FORTRAN is a convenient way to give input to a
program in a formatted file, read at runtime by the program to setup its
execution behaviour. So the next step is somewhat tricky, as you need to edit
the namelist file respecting its well defined syntax. Open your preferred text
file editor and load the \verb=test_001.in= file. You will need to modify for
the scope of the present tutorial the following lines:

\begin{Verbatim}
FROM:
 dirter = '/set/this/to/where/your/domain/file/is',
TO:
 dirter = 'input/',
\end{Verbatim}

\begin{Verbatim}
FROM:
 inpter = '/set/this/to/where/your/surface/dataset/is',
TO:
 inpter = '$REGCM_GLOBEDAT',
\end{Verbatim}

where \verb=$REGCM_GLOBEDAT= is the directory where input data have been
downloaded in chapter \ref{obdata}.

\begin{Verbatim}
FROM:
 dirglob = '/set/this/to/where/your/icbc/for/model/is',
TO:
 dirglob = 'input/',
\end{Verbatim}

\begin{Verbatim}
FROM:
 inpglob = '/set/this/to/where/your/input/global/data/is',
TO:
 inpglob = '$REGCM_GLOBEDAT',
\end{Verbatim}

and last bits:

\begin{Verbatim}
FROM:
 dirout='/set/this/to/where/your/output/files/will/be/written'
TO:
 dirout='output/'
\end{Verbatim}

These modifications just reflect the above directory layout proposed for this
tutorial, and any of these paths can point anywhere on your system disks. The path
is limited to $256$ characters.
We are now ready to execute the first program of the RegCM model.

\section{Create the DOMAIN file using terrain}

The first step is to create the DOMAIN file to localize the model on a world region.
The program which does this for you reading the global databases is
\verb=terrain= .

To launch the terrain program, enter the following commands:

\begin{Verbatim}
$> cd $REGCM_RUN
$> ./bin/terrain test_001.in
\end{Verbatim}

If everything is correctly configured up to this point, the model should print
something on stdout, and the last lines will be:

\begin{Verbatim}
 Grid data written to output file                                               
 Successfully completed terrain fields generation
\end{Verbatim}

In the input directory the program will write the following two files:

\begin{Verbatim}
$> ls input
test_001_DOMAIN000.nc test_001_LANDUSE
\end{Verbatim}

The DOMAIN file contains the localized topography and landuse databases, as
well as projection information and land sea mask. The second file is an ASCII
encoded version of the landuse, used for modifying it on request. We will cover
it's usage later on.  To have a quick look at the DOMAIN file content, you may want
to use the GrADSNcPlot program:

\begin{Verbatim}
$> ./bin/GrADSNcPlot input/test_001_DOMAIN000.nc
\end{Verbatim}

If not familiar with GrADS program, enter in sequence the following commands at
the \verb=ga->= prompt:

\begin{Verbatim}
ga-> q file
ga-> set gxout shaded
ga-> set mpdset hires
ga-> set cint 50
ga-> d topo
ga-> c
ga-> set cint 1
ga-> d landuse
ga-> quit
\end{Verbatim}

this will plot the topography and the landuse on the X11 window.

\section{Create the SST using the sst program}

We are now ready to create the Sea Surface Temperature for the model, reading a
global dataset.
The program which does this for you is the \verb=sst= program, which is executed
with the following commands:

\begin{Verbatim}
$> cd $REGCM_RUN
$> ./bin/sst test_001.in
\end{Verbatim}

If everything is correctly configured up to this point, the model should print
something on stdout, and the last line will be:

\begin{Verbatim}
 Successfully generated SST
\end{Verbatim}

The input directory now contains a new file:

\begin{Verbatim}
$> ls input
test_001_DOMAIN000.nc test_001_LANDUSE test_001_SST.nc
\end{Verbatim}

The SST file contains the Sea Surface temperature to be used in generating the
Initial and Boundary Conditions for the model for the period specified in the
namelist file. Again you may want to use the GrADSNcPlot program to look at
file content:

\begin{Verbatim}
$> ./bin/GrADSNcPlot input/test_001_SST.nc
\end{Verbatim}

If not familiar with GrADS program, enter in sequence the following commands at
the \verb=ga->= prompt:

\begin{Verbatim}
ga-> q file
ga-> set gxout shaded
ga-> set mpdset hires
ga-> set cint 2
ga-> d sst
ga-> quit
\end{Verbatim}

this will plot the interpolated sst field on the X11 window.

\section{Create the ICBC files using the icbc program}

Next step is to create the ICBC (Initial Condition, Boundary Conditions) for
the model itself. The program which does this for you is the \verb=icbc=
program, executed with the following commands:

\begin{Verbatim}
$> cd $REGCM_RUN
$> ./bin/icbc test_001.in
\end{Verbatim}

If everything is correctly configured up to this point, the model should print
something on stdout, and the last line will be:

\begin{Verbatim}
 Successfully completed ICBC
\end{Verbatim}

The input directory now contains two more files:

\begin{Verbatim}
$> ls -1 input
test_001_DOMAIN000.nc
test_001_ICBC.1990060100.nc
test_001_ICBC.1990070100.nc
test_001_LANDUSE
test_001_SST.nc
\end{Verbatim}

The ICBC files contain the surface pressure, surface temperature, horizontal
3D wind components, 3D temperature and mixing ratio for the RegCM domain for the
period and time resolution specified in the input file.
Again you may want to use the GrADSNcPlot program to look at file content:

\begin{Verbatim}
$> ./bin/GrADSNcPlot input/test_001_ICBC.1990060100.nc
\end{Verbatim}

If not familiar with GrADS program, enter in sequence the following commands at
the \verb=ga->= prompt:

\begin{Verbatim}
ga-> q file
ga-> set gxout shaded
ga-> set mpdset hires
ga-> set cint 2
ga-> d ts
ga-> c
ga-> set lon 10
ga-> set lat 43
ga-> set t 1 last
ga-> d ts
ga-> quit
\end{Verbatim}

this will plot the interpolated surface temperature field on the X11 window,
first at first time step and then a time section in one of the domain points
for a whole month.

We are now ready to run the model!

\section{First RegCM model simulation}

The model has now all needed data to allow you to launch a test simulation,
the final goal of our little tutorial.

The model command line now will differ if you have prepared the Serial or the
MPI version. For the MPI enabled version we will assume that your machine is
a dual core processor (baseline for current machines, even for laptops).
Change the \verb=-np 2= argument to the number of processors you have on
Your platform (on my laptop QuadCore I use \verb=-np 4=).

\begin{itemize}
\item MPI version \footnote{Use regcmMPICLM if the CLM version has been
  configured}
\begin{Verbatim}
$> cd $REGCM_RUN
$> mpirun -np 8 ./bin/regcmMPI test_001.in
\end{Verbatim}
\item Serial version \footnote{Deprecated. Support will be dropped in future
releases.}
\begin{Verbatim}
$> cd $REGCM_RUN
$> ./bin/regcmSerial test_001.in
\end{Verbatim}
\end{itemize}

Now the model will start running, and a series of diagnostic messages will be
printed on screen. As this is a simulation known to behave well, no stoppers
will appear, so you may want now to have a coffee break and come back in 10
minutes from now.

At the end of the run, the model will print the following message:

\begin{Verbatim}
 RegCM V4 simulation successfully reached end
\end{Verbatim}

The output directory now contains four files:

\begin{Verbatim}
$> ls output
test_001_ATM.1990060100.nc test_001_SRF.1990060100.nc
test_001_RAD.1990060100.nc test_001_SAV.1990070100.nc
\end{Verbatim}

the ATM file contains the atmosphere status from the model, the SRF file
contains the surface diagnostic variables, and the RAD file contains radiation
fluxes information. The SAV file stores the status of the model at the end of
the simulation period to enable a restart, thus allowing a long simulation
period to be splitted in shorter simulations.

To have a look for example at surface fields, you may want to use the
following command:

\begin{Verbatim}
$> ./bin/GrADSNcPlot output/test_001_SRF.1990060100.nc
\end{Verbatim}

Assuming the previous crash course in using GraDS was received, you should be
able to plot the variables in the file.

This is the end of this little tutorial, and in the next chapter we will
examine how to configure the model for your research needs.

