s_outp_pkgs/text/grid_gen.tex

% $Header: /u/gcmpack/manual/s_outp_pkgs/text/grid_gen.tex,v 1.3 2006/06/30 20:53:52 edhill Exp $
% $Name:  $

\section{Grid Generation}
\label{sec:pkg:grid_gen}
\begin{rawhtml}
<!-- CMIREDIR:package_grid_gen: -->
\end{rawhtml}


The horizontal discretizations within MITgcm have been written to work
with many different grid types including:
\begin{itemize}
\item cartesian coordinates
\item spherical polar (``latitude-longitude'') coordinates
\item general curvilinear orthogonal coordinates
\end{itemize}
The last of these, especially when combined with the domain
decomposition capabilities of MITgcm, allows a great degree of grid
flexibility.  To date, general curvilinear orthogonal coordinates have
been used primarily (in fact, almost exclusively) in conjunction with
so-called ``cube-sphere'' grids.  However, it is important to observe
that cube-sphere arrangements are only one example of what is possible
with domain-decomposed logically rectangular regions each containing
curvilinear orthogonal coordinate systems.  Much more sophisticated 
domains can be imagined and constructed.

In order to explore the possibilities of domain-decomposed curvilinear
orthogonal coordinate systems, a suite of grid generation software
called ``SPGrid'' (for SPherical Gridding) has been developed.  SPGrid
is a relatively new facility and papers detailing its algorithms are
in preparation.  Althogh SPGrid is new and rapidly developing, it has
already demonstrated the ability to generate some useful and
interesting grids.

This section provides a very brief introduction to SPGrid and shows
some early results.  For further information, please contact the
MITgcm support list at:
\begin{center}
  MITgcm-support@mitgcm.org
\end{center}


\subsection{Using SPGrid}

The SPGrid software is not a single program.  Rather, it is a
collection of C++ code and MatLAB scripts that can be used as a
framework or library for grid generation and manipulation.  Currently,
grid creation is accomplished by either directly running matlab
scripts or by writing a C++ ``driver'' program.  The matlab scripts
are suitable for grids composed of a single ``face'' (that is, a
single logically rectangular region on the surface of a sphere).  The
C++ driver programs are appropriate for grids composed of multiple
connected logically rectangular patches.  Each driver is program is
written to specify the shape and connectivity of tiles and the
preferred grid density (that is, the number of grid cells in each
logical direction) and edge locations of the cells where they meet the
edges of each face.  The driver programs pass this information to the
SPGrid library which generates the actual grid and produces the output
files that describe it.

Currently, driver programs are available for a few examples including
cubes, ``lat-lon caps'' (cube topologies that have conformal caps at
the poles and are exactly lat-lon channels for the remainder of the
domain), and some simple ``embedded'' regions that are meant to be
used within typical cubes or traditional lat-lon grids.

To create new grids, one may start with an existing driver program and
modify it to describe a domain that has a different arrangement.  The
number, location, size, and connectivity of grid ``faces'' (the name
used for the logically rectangular regions) can be readily changed.
Further, the number of grid cells within faces and the location of
the grid cells at the face edges can also be specified.


\subsubsection{SPGrid Requirements}

The following programs and libraries are required to build and/or run
the SPGrid suite:
\begin{itemize}
\item MatLAB is a run-time requirement since many of the generation
  algorithms have been written as MatLAB scripts: \\
  \begin{rawhtml} <A href="http://www.mathworks.com"> \end{rawhtml}
  \texttt{http://www.mathworks.com}
  \begin{rawhtml} </A> \end{rawhtml}

\item the Wild Magic graphics engine (a C++ library) is needed for the
  main ``driver'' code: \\
  \begin{rawhtml} <A href="http://geometrictools.com/"> \end{rawhtml}
  \texttt{http://geometrictools.com/}
  \begin{rawhtml} </A> \end{rawhtml}

\item the NetCDF library is needed for file I/O: \\
  \begin{rawhtml} <A href="http://www.mathworks.com"> \end{rawhtml}
  \texttt{http://www.mathworks.com}
  \begin{rawhtml} </A> \end{rawhtml}

\item the BOOST Serialization library is used for I/O: \\
  \begin{rawhtml} <A href="http://www.boost.org"> \end{rawhtml}
  \texttt{http://www.boost.org}
  \begin{rawhtml} </A> \end{rawhtml}

\item a typical Linux/Unix build environment including the make
  utility (preferably Gnu Make) and a C++ compiler (SPGrid was
  developed with g++ v4.x).
\end{itemize}


\subsubsection{Obtaining SPGrid}

The latest version can be obtained from:
\begin{center}
  \begin{rawhtml}
     <A href="http://mitgcm.org/~edhill/grids/spgrid_releases/">
  \end{rawhtml}
  \texttt{http://mitgcm.org/$\sim$edhill/grids/spgrid\_releases/}
  \begin{rawhtml} </A> \end{rawhtml}
\end{center}


\subsubsection{Building SPGrid}

The procedure for building is similar to many open source projects:
\begin{verbatim}
     tar -xf spgrid-0.9.4.tar.gz
     cd spgrid-0.9.4
     export CPPFLAGS="-I/usr/include/netcdf-3"
     export LDFLAGS="-L/usr/lib/netcdf-3"
     ./configure
     make
\end{verbatim}
where the \texttt{CPPFLAGS} and \texttt{LDFLAGS} environment variables
can be edited to reflect the locations of all the necessary
dependencies.  SPGrid is known to work on Fedora Core Linux (versions
4 and 5) and is likely to work on most any Linux distribution that
provides the needed dependencies.


\subsubsection{Running SPGrid}

Within the \texttt{src} sub-directory, various example driver programs
exist.  These examples describe small, simple domains and can generate
the input files (formatted as either binary \texttt{*.mitgrid} or
netCDF) used by MITgcm.

One such example is called ``SpF\_test\_cube\_cap'' and it can be run
with the following sequence of commands:
\begin{verbatim}
     cd spgrid-0.9.4/src
     make SpF_test_cube_cap
     mkdir SpF_test_cube_cap.d
     ( cd SpF_test_cube_cap.d && ln -s ../../scripts/*.m . )
     ./SpF_test_cube_cap
\end{verbatim}
which should create a series of output files:
\begin{verbatim}
     SpF_test_cube_cap.d/grid_*.mitgrid
     SpF_test_cube_cap.d/grid_*.nc
     SpF_test_cube_cap.d/std_topology.nc
\end{verbatim}
where the \texttt{grid\_*.mitgrid} and \texttt{grid\_*.nc} files
contain the grid information in binary and netCDF formats and the
\texttt{std\_topology.nc} file contains the information describing the
connectivity (both edge--edge and corner--corner contacts) between all
the faces.


\subsection{Example Grids}

The following grids are various examples created with SPGrid. 
1	% $Header: /u/gcmpack/manual/s_outp_pkgs/text/grid_gen.tex,v 1.3 2006/06/30 20:53:52 edhill Exp $
2	% $Name: $
3
4	\section{Grid Generation}
5	\label{sec:pkg:grid_gen}
6	\begin{rawhtml}
7	<!-- CMIREDIR:package_grid_gen: -->
8	\end{rawhtml}
9
10
11	The horizontal discretizations within MITgcm have been written to work
12	with many different grid types including:
13	\begin{itemize}
14	\item cartesian coordinates
15	\item spherical polar (``latitude-longitude'') coordinates
16	\item general curvilinear orthogonal coordinates
17	\end{itemize}
18	The last of these, especially when combined with the domain
19	decomposition capabilities of MITgcm, allows a great degree of grid
20	flexibility. To date, general curvilinear orthogonal coordinates have
21	been used primarily (in fact, almost exclusively) in conjunction with
22	so-called ``cube-sphere'' grids. However, it is important to observe
23	that cube-sphere arrangements are only one example of what is possible
24	with domain-decomposed logically rectangular regions each containing
25	curvilinear orthogonal coordinate systems. Much more sophisticated
26	domains can be imagined and constructed.
27
28	In order to explore the possibilities of domain-decomposed curvilinear
29	orthogonal coordinate systems, a suite of grid generation software
30	called ``SPGrid'' (for SPherical Gridding) has been developed. SPGrid
31	is a relatively new facility and papers detailing its algorithms are
32	in preparation. Althogh SPGrid is new and rapidly developing, it has
33	already demonstrated the ability to generate some useful and
34	interesting grids.
35
36	This section provides a very brief introduction to SPGrid and shows
37	some early results. For further information, please contact the
38	MITgcm support list at:
39	\begin{center}
40	MITgcm-support@mitgcm.org
41	\end{center}
42
43
44	\subsection{Using SPGrid}
45
46	The SPGrid software is not a single program. Rather, it is a
47	collection of C++ code and MatLAB scripts that can be used as a
48	framework or library for grid generation and manipulation. Currently,
49	grid creation is accomplished by either directly running matlab
50	scripts or by writing a C++ ``driver'' program. The matlab scripts
51	are suitable for grids composed of a single ``face'' (that is, a
52	single logically rectangular region on the surface of a sphere). The
53	C++ driver programs are appropriate for grids composed of multiple
54	connected logically rectangular patches. Each driver is program is
55	written to specify the shape and connectivity of tiles and the
56	preferred grid density (that is, the number of grid cells in each
57	logical direction) and edge locations of the cells where they meet the
58	edges of each face. The driver programs pass this information to the
59	SPGrid library which generates the actual grid and produces the output
60	files that describe it.
61
62	Currently, driver programs are available for a few examples including
63	cubes, ``lat-lon caps'' (cube topologies that have conformal caps at
64	the poles and are exactly lat-lon channels for the remainder of the
65	domain), and some simple ``embedded'' regions that are meant to be
66	used within typical cubes or traditional lat-lon grids.
67
68	To create new grids, one may start with an existing driver program and
69	modify it to describe a domain that has a different arrangement. The
70	number, location, size, and connectivity of grid ``faces'' (the name
71	used for the logically rectangular regions) can be readily changed.
72	Further, the number of grid cells within faces and the location of
73	the grid cells at the face edges can also be specified.
74
75
76	\subsubsection{SPGrid Requirements}
77
78	The following programs and libraries are required to build and/or run
79	the SPGrid suite:
80	\begin{itemize}
81	\item MatLAB is a run-time requirement since many of the generation
82	algorithms have been written as MatLAB scripts: \\
83	\begin{rawhtml} <A href="http://www.mathworks.com"> \end{rawhtml}
84	\texttt{http://www.mathworks.com}
85	\begin{rawhtml} </A> \end{rawhtml}
86
87	\item the Wild Magic graphics engine (a C++ library) is needed for the
88	main ``driver'' code: \\
89	\begin{rawhtml} <A href="http://geometrictools.com/"> \end{rawhtml}
90	\texttt{http://geometrictools.com/}
91	\begin{rawhtml} </A> \end{rawhtml}
92
93	\item the NetCDF library is needed for file I/O: \\
94	\begin{rawhtml} <A href="http://www.mathworks.com"> \end{rawhtml}
95	\texttt{http://www.mathworks.com}
96	\begin{rawhtml} </A> \end{rawhtml}
97
98	\item the BOOST Serialization library is used for I/O: \\
99	\begin{rawhtml} <A href="http://www.boost.org"> \end{rawhtml}
100	\texttt{http://www.boost.org}
101	\begin{rawhtml} </A> \end{rawhtml}
102
103	\item a typical Linux/Unix build environment including the make
104	utility (preferably Gnu Make) and a C++ compiler (SPGrid was
105	developed with g++ v4.x).
106	\end{itemize}
107
108
109	\subsubsection{Obtaining SPGrid}
110
111	The latest version can be obtained from:
112	\begin{center}
113	\begin{rawhtml}
114	<A href="http://mitgcm.org/~edhill/grids/spgrid_releases/">
115	\end{rawhtml}
116	\texttt{http://mitgcm.org/$\sim$edhill/grids/spgrid\_releases/}
117	\begin{rawhtml} </A> \end{rawhtml}
118	\end{center}
119
120
121	\subsubsection{Building SPGrid}
122
123	The procedure for building is similar to many open source projects:
124	\begin{verbatim}
125	tar -xf spgrid-0.9.4.tar.gz
126	cd spgrid-0.9.4
127	export CPPFLAGS="-I/usr/include/netcdf-3"
128	export LDFLAGS="-L/usr/lib/netcdf-3"
129	./configure
130	make
131	\end{verbatim}
132	where the \texttt{CPPFLAGS} and \texttt{LDFLAGS} environment variables
133	can be edited to reflect the locations of all the necessary
134	dependencies. SPGrid is known to work on Fedora Core Linux (versions
135	4 and 5) and is likely to work on most any Linux distribution that
136	provides the needed dependencies.
137
138
139	\subsubsection{Running SPGrid}
140
141	Within the \texttt{src} sub-directory, various example driver programs
142	exist. These examples describe small, simple domains and can generate
143	the input files (formatted as either binary \texttt{*.mitgrid} or
144	netCDF) used by MITgcm.
145
146	One such example is called ``SpF\_test\_cube\_cap'' and it can be run
147	with the following sequence of commands:
148	\begin{verbatim}
149	cd spgrid-0.9.4/src
150	make SpF_test_cube_cap
151	mkdir SpF_test_cube_cap.d
152	( cd SpF_test_cube_cap.d && ln -s ../../scripts/*.m . )
153	./SpF_test_cube_cap
154	\end{verbatim}
155	which should create a series of output files:
156	\begin{verbatim}
157	SpF_test_cube_cap.d/grid_*.mitgrid
158	SpF_test_cube_cap.d/grid_*.nc
159	SpF_test_cube_cap.d/std_topology.nc
160	\end{verbatim}
161	where the \texttt{grid\_.mitgrid} and \texttt{grid\_.nc} files
162	contain the grid information in binary and netCDF formats and the
163	\texttt{std\_topology.nc} file contains the information describing the
164	connectivity (both edge--edge and corner--corner contacts) between all
165	the faces.
166
167
168	\subsection{Example Grids}
169
170	The following grids are various examples created with SPGrid.