\chapter{Conformal mapping tool\label{chp:confmap}}
The HYCOM model is defined on a two-dimensional lattice of points, with each
point describing a scalar variable on this lattice given by an index pair
$(i,j)$. This point is usually referred to as the $p$-point.
The grid is a so-called Arakawa C-grid where $u$ and $v$ velocity points
are offset from the $p$-point.
The first velocity
component ($u$) is placed on the midpoint between two neighbouring $p$-points
$(i-1,j)$ and $(i,j)$ The second velocity component ($v$) is placed on the 
midpoint between two neighbouring $p$-points $(i,j-1)$ and $(i,j)$. See
\autoref{fig:grid} for an illustration.

In HYCOM the actual location of the grid lattice on the earth is described by
the variables plon,plat ($p$-points), ulon,ulat ($u$-points) and vlon, vlat
($v$-points), given in the file regional.grid.[ab]. We will loosely refer to the
lattice of grid points $(i,j)$ and the information of the geographical positions
of $u$, $v$, and $p$-points as the ``model grid''.

The model grid is a unique feature of the region setup.  For different
experiments you may change the topography, the forcing, code features etc, but
the grid files (\file{regional.grid.[ab]}) should not change. These files determine the
longitude and latitude of grid points, as well as distances between grid
nodes. The files related to the model grid should be placed in the \file{topo/}
subdirectory. This includes the files \file{regional.grid.[ab]}, the conformal mapping
file {\it grid.info}, and also old grid files such as \file{latlon.dat} and
\file{newpos.uf}.  The two latter files are rarely needed anymore, but its ok to 
keep them in the \file{topo/} directory just in case.

The creation of a model grid at NERSC is usually done with the conformal mapping
routine ``grid'', which can be found in the directory {\it
\$MSCPROGS/bin\_setup/}. It is also possible to set up a new grid using tools
supplied in standard HYCOM. Routines for this can be found under the directory
{\it \$HYCOM\_ALL/topo/}. Many of the tools found under {\it \$MSCPROGS/} depend on the
grid being a conformal mapping grid, however, so to use these it is safest to
use the conformal mapping grids.

\section{Input files}

\section{Model Grid generation with the conformal mapping tools}

The conformal mapping routines \citep{ben99} defines the mapping from the
two-dimensional lattice of points given by grid indexes $(i,j)$ to their
geographical location in longitude and latitude coordinates. This makes it
possible to place a model grid in a region with great flexibility, or to 
create global grids which avoid the singularities at the poles. It also 
makes it possible to shape the grids without too much distortion (variation of
grid size as one moves from one grid cell to the next). This is
important since too much distortion can affect the effective precision of
numerical schemes. 

The conformal mapping tools rely on a input file called grid.info. This file
determines the location of the model grid, and can also be used to set the
bathymetry. Its contents look somewhat like this (line numbers added for
reference in the text)
\begin{verbatim}
line 1 :    -40.0 140.0     ! Position of pole N (lattitude, longitude):
line 2 :    -50.0 140.0     ! Position of pole S (lattitude, longitude):
line 3 :    177.5 182.7 200 ! Longitude interval West lon,   East lon, idim
line 4 :      3.0  80.0 220 ! Lattitude interval south limit, north limit, jdim
line 5 :   .false.          ! Generate topography
line 6 :   .true.           ! dump teclatlon.dat
line 7 :   .true.           ! dump micom latlon.dat
line 8 :   .true.           ! mercator grid (true, false)
line 9 :   -2.6 .false.     ! merc fac
line 10:   .false.          ! Smoothing, Shapiro filter
line 11:   8   2            ! Order of Shapiro filter,  number of passes
\end{verbatim}

The two first lines of this file determines the location of the north and south
poles  for the new grid. These can be placed anywhere on the earth - if they are
placed on opposite sides of the earth, the result is a lon/lat grid in the
new coordinates which are similar to standard lon/lat coordinates (though
usually not co-located). An example is shown in figure~\ref{fig:geopoles}
where the North and South poles of the grid are placed at the geographical North
and South poles. Note how the constant longitude grid lines follow great
circles, as with usual longitude coordinates.
\begin{figure}[bt]
  \subfloat[New poles of the conformal mapping co-located with actual north and
  south poles\label{fig:geopoles}]%
     {\includegraphics[width=.45\textwidth]{Pics/cm_polesasold}}
  \subfloat[New North Pole of the conformal mapping shifted towards
  Siberia\label{fig:dispNpole}]%
     {\includegraphics[width=.45\textwidth]{Pics/cm_northpolemoved}}
  \caption{The effect of moving the new poles of the conformal mapping routine}
  \label{3figs}
\end{figure}

If we shift the North Pole of the grid towards Siberia, as in figure
\ref{fig:dispNpole}, the result is a grid with curved lines relative to great
circles.  By manipulating the location of the poles like this, it is possible to
set up a grid with focused resolution in key areas, and lower resolution in less
interesting areas. Figure~\autoref{fig:dispNpole} also illustrates how the conformal
mapping tool can be set up so that singularities of the model grid (North/South 
poles) are on land.

Line three and four of grid.info determine the placement of your grid and the
size of the grid. While you can use the conformal mapping tools to set up a
global grid, you can also set it up to give a grid covering  only a part of the
globe, which is useful for creating grids covering specific regions. The third line
of grid.info specifies the  East-West longitude interval, along with the number
of grid points over this range:
\begin{verbatim}
line 3 :    177.5 182.7 200 ! Longitude interval West lon,   East lon, idim
\end{verbatim}
It is important to remember that the longitude interval is in the new
coordinates defined by your initial placement of the new North and South Poles.
By specifying a range which is less than 360 degrees, you will create a regional
grid (i.e not global). Choosing the correct values for the limits depends on the
placement of the poles and how far apart they are. It can be hard to visualize
this so some trial and error may be required to get the correct placement. It is
often a good idea to start with a wide logitude range  to get the big picture.  

The fourth line is the greatest source of confusion, in the example it reads:
\begin{verbatim}
line 4 :      3.0  80.0 220 ! Lattitude interval south limit, north limit, jdim
\end{verbatim}
The confusion is often related to the setting of the mercator factor, given on
line 9.
\begin{verbatim}
line 9 :   -2.6 .false.     ! merc fac
\end{verbatim}
If the logical value on this line is set to .false. (which is generally
recommended), the grid tool will try to create equal area grid cells. This means
that the grid cell size is uniquely determined by the settings on line 3.
This lays restrictions on the way the north and south limits of the grid can be
set. In stead of setting the north-south range of the grid, you can now only adjust
the southern limit of the grid. The southern limit of the grid is not set on
line 3, however, it is set by the floating-point value on line 9 (!)

The placement of the grid will not be described in detail here, it is usually a 
process of trial and error. It is also hard to generalize the process. The
following illustrations should hopefully be of some assistance, though. The main
assumption here is that you have decided on the positions of the poles, and what
remains is to move the grid to its final placement.
%
The images of Figure~\ref{fig:gridmod} will illustrate some of the effects
of changing east/west limits and the merc fac southern limit.
\begin{figure}[bt]
\begin{center}
  \subfloat[Original Grid\label{fig:gridorig}]%
     {\includegraphics[width=.32\textwidth]{Pics/cmorig}}  
  \subfloat[Increasing east-west range\label{fig:modew}]% 
     {\includegraphics[width=.32\textwidth]{Pics/cm_incr_ew_limits}}
  \subfloat[Increasing grid points along east-west direction\label{fig:modnx}]%
     {\includegraphics[width=.32\textwidth]{Pics/cm_incrnx_200_250}} \\
  \subfloat[Increasing Mercator Factor\label{fig:gridmfac}]%
     {\includegraphics[width=.32\textwidth]{Pics/cm_mfac_-2p6_-1p6}}
  \subfloat[Increasing grid points along north-south direction\label{fig:gridny}]%
     {\includegraphics[width=.32\textwidth]{Pics/cm_incrny_220_280}}
  \caption{The effect of changing values in the grid.info file. Red is original
  grid, green is grid after modifying one set of values.}
  \label{fig:gridmod}
\end{center}
\end{figure}

The original grid is given in Figure~\ref{fig:gridorig}. It corresponds to the
grid.info file given at the start of this section. It is placed over the North
Atlantic and the Arctic, and is same grid as the one used in TOPAZ3. 
Now suppose that some changes to the grid placement are needed. The grid can be
shifted
east-west by modifying the eastern and western limits, and at the same time
keeping the east-west range constant. Once we start to change the east-west
range or the number of points in the east-west direction, however, the grid
might change in non-intuitive ways. The following describes some of the most
common pitfalls. Note that grid directions refer to the new longitude and
latitude coordinates, not actual longitude and latitude,

%\begin{description}
\paragraph{Inreasing the east-west range} When the east-west range is changed,
this will also change the size of grid cells. As the grid length is set to be the
same in the east-west and north-south direction, this means that a change in
east-west range will affect the north-south range of your grid.
Figure~\ref{fig:modew} illustrates this. In this case the east-west range is
increased. As the east-west range is increased the grid cells will increase in
size, both in east-west and north-south direction. This means that the northern
limit of the grid will increase as well. This is seen in Figure~\ref{fig:modew}
where the increased east-west range has lead to a increased coverage in both the
east-west and north-south directions. (Red=original grid, Green=changed grid).
%
The opposite effect is seen when {\it reducing} the east-west range.
%
Because of this behaviour, one should be  careful not to increase the 
east-west range so much that the northern edge of the grid ``hits'' the north pole.
\paragraph{Increasing grid points in the east-west direction} When 
number of points in the east-west direction is increased, the effect will be to decrease the
size of the grid cells. Since the grid cell size in the north-south direction is
decreased correspondingly, this will lead to the northern edge of the grid
moving southward.  This is seen in Figure~\ref{fig:modnx}. Note that the grid
covers the same range in the east-west direction, while the northern limit of
the new grid (in green) has moved towards the south. The opposite movement of
the northern edge of the grid will happen when you reduce the grid points in the
east-west direction.
\paragraph{Increasing the Mercator Factor} When the mercator factor is increased, the
new grid will shift towards the north in the new latitude direction. This is illustrated
in Figure~\ref{fig:gridmfac}. Note that the east-west range stays the same. The
opposite effect will happen when you reduce the mercator factor. As previously
mentioned only the  mercator factor should be modified when the grid is to be
shifted in the north-south direction. One should be careful not to increase the
southern limit so much that the northern edge of the grid ``hits'' the north
pole.
\paragraph{Increasing the grid points in the south-north direction} When you increase
the grid points in the south-north direction, the size of grid cells will not
change. This means that increasing the grid points leads to a northward shift in
the northern edge of the grid. This is illustrated in Figure~\ref{fig:gridny}. The
opposite will happen when you reduce the grid points in the south-north
direction. 
\paragraph{Adjusting resolution while keeping the same coverage} To keep the coverage
of the grid, while increasing/reducing the resolution, you should multiply the
grid points in the east-west and north-south direction by the same factor.

\subsubsection{Final tips} 
The grid tool is very flexible, but not always intuitive
to use. Because of this, it is hard to give a single recipe for setting up a
grid. Some general guidelines can be given, however:
\begin{itemize}
\item Decide on pole placements first, it can be hard to adjust them when you
have "zoomed in" on a region
\item Start with a wide east-west range and low resolution to begin with. This
way its easier to locate your grid in matlab (for instance)
\item Change one parameter at a time - changing more than one at a time can
change the grid placement in spectacular ways
\item Use small increments - make fequent backups of grid.info
\item Use a good tool to visualize the grid. A matlab routine "showconfmap" is
designed for this. It runs the "grid" routine, and plots the grid on a map
projection (requires the m\_map matlab toolbox)
\item Switch off topography generation until you are reasonably happy with the
grid placement - this significantly speeds up the grid routine.
\end{itemize}





