\chapter{Create a Global Grid}
\label{chap:global-grids}
In this section, we show how to create a global grid with \Atlas.
We remind the reader that global grid refers to a grid covering 
the entire sphere (e.g. the entire earth for instance).
In addition, with the term \textit{grid} we intend a 
list of points without any specific connectivity rule.

As explained in \chap{chap:structure}, \Atlas supports various 
global grids. Within the library, these grids are identified 
by some convenient keys. In the rest of the chapter we will 
divide the various global grids available in the following 
macro areas:
%
\begin{itemize}
\item Structured grids,
\item Unstructured grids.
\end{itemize} 
%
and we will specify the keys needed to automatically generate 
a given grid in both C++ and Fortran. Note that it is also possible 
to create a grid manually, however this approach is not currently 
explained in this document.
It is also important to remark that for the Structured grids, the memory
footprint is negligible since the information regarding the points are not 
stored but are computed at runtime when requested.
The last typology, unstructured, has instead a non-negligible memory 
footprint since in this case the points are effectively stored in memory.



\section{Structured Grids}
There exists various subsets of structured grids in \Atlas.
All of them can be constructed using the same method
called \inltc{Structured::create()}. In particular, we need to pass 
a predefined key identifying the grid we want to create 
to the constructor in order to generate the object grid. 
This object, in turn, contains various methods that allows 
the user to retrieve the number of points of the generated 
grid, the number of longitudes and latitudes, and the 
coordinates a given longitude and latitude.

The predefined keys existing in \Atlas for Gaussian grids 
are reported in the following:
%
\begin{itemize}
\item Classic reduced Gaussian grid --- \inltc{N\#},
\item Regular Gaussian grid --- \inltc{F\#},
\item Octahedral reduced Gaussian grid --- \inltc{O\#},
\end{itemize}
%
where \inltc{\#} represents the number of latitudes 
in one hemisphere.
%
\begin{itemize}
\item RegularLonLat --- \inltc{L\#} or \inltc{L\#$\times$\#}
\item ShiftedLonLat --- \inltc{S\#} or \inltc{S\#$\times$\#}
\end{itemize}
%
where in the alternative key, the first \inltc{\#} represents the total number 
of longitudes, while the second \inltc{\#} specifies the total number of 
latitudes from pole to pole.

In the next two subsections we will present two simple 
examples, the first in C++ and the second in Fortran, 
to generate global grids through the predefined keys 
just outlined. We will also show how to retrieve some 
useful information regarding the grid generated.

\subsection{C++ version}
The \lista{Structured-C} shows how to construct a generic
structured grid.
%
\lstinputlisting[caption=Generating a Gaussian grid with 
\Atlas using C++, style=CStyle, label=Structured-C]{global-grids-Structured.cc}
%
We create the global 
grid object (see line 14). In particular, we call the 
grid constructor passing the command-line string (that 
represents the key of the grid we want to create) to it.
The default value is set to \inltc{O32}, that represents 
a octahedral reduced Gaussian grid with 32 latitudes in one hemisphere 
(i.e. 64 latitudes in total).  
The command-line string (i.e. the key) must be contained 
in the predefined keys for reduced grid generation as specified 
before. If the user uses a non-existent keyword, there will 
appear an error message.
The grid object, \inltc{grid}, is 
a \inltc{Structured} type and it will allow 
us to access some useful information about the grid.  

It is now possible to run this simple program by using one 
command-line argument representing the keyword that identifies 
an \Atlas predefined grid. For instance, we can execute the 
following command line
%
\begin{lstlisting}[style=BashStyle]
./atlas_c-global-grids-Structured
\end{lstlisting}
% 
This will generate an octahedral reduced Gaussian grid with 
32 latitudes on one hemisphere (i.e. 64 latitudes in total).

The output to the screen of the code we just executed 
contains some useful information regarding the grid. 

In particular, the first three numbers represent the 
number of latitudes, longitudes and points of the structured
grid, respectively. Note that we can directly access them 
through the \inltc{grid} object (see lines 19, 20, 21).
\begin{tipbox}
For the number of latitudes and points we do not need to provide
any argument to the function retrieving the information. On the 
other hand, for the number of longitudes we do need to additionally 
provide the index of a specific latitude, since the number of 
longitudes may depend on the latitude (see \chap{chap:structure} 
for more details on how a structured grid is constructed). 
\end{tipbox}

The last three numbers represent the coordinates of a given 
latitude, longitude and both longitude and latitude together, 
respectively. Note again how these information can be directly 
accessed through the object \inltc{grid}. 
Also, for retrieving a given latitude coordinate it is only 
necessary to specify one index that refers to that particular 
latitude (see line 23). On the other hand, for a given longitude 
we need to provide both the index of the latitude and the index 
of the longitude, since the longitude may depend on the latitude 
(see line 21 and 24).

\subsection{Fortran version}
The \lista{Structured-F} shows how to construct a generic 
structured grid.

%
\lstinputlisting[caption=Generating a Gaussian grid with \Atlas 
using Fortran, style=FStyle, label=Structured-F]{global-grids-Structured.F90}
%

We create the global 
grid object (see line 9). In particular, we call 
the grid constructor passing the command-line string 
(that represents the key of the grid we want to create) to 
it. The default value is set to \inltc{O32}, that represents 
a octahedral reduced Gaussian grid with 32 latitudes in one hemisphere 
(i.e. 64 latitudes in total).  
The grid object, \inltc{grid}, is 
an \inltc{atlas\_grid\_Structured} type and it will allow 
us to access some useful information about the grid.  

It is now possible to run this simple program with the following command line 
%
\begin{lstlisting}[style=BashStyle]
./atlas_f-global-grids-Structured
\end{lstlisting}
% 
This will generate an octahedral reduced Gaussian grid 
with 32 latitudes on one emisphere (i.e. 64 latitudes 
in total).

The output to the screen of the code we just executed 
contains some useful information regarding the grid.

In particular, the first three numbers represent the 
number of latitudes, longitudes and points of the grid,
respectively. Note that we can directly access them 
through the \inltc{grid} object (see lines 11, 14, 17).
%
\begin{tipbox}
For the number of latitudes and points we do not need to provide
any argument to the function retrieving the information. On the 
other hand, for the number of longitudes we do need to additionally 
provide the index of a specific latitude, since the number of 
longitudes may depend on the latitude (see \chap{chap:structure} 
for more details on how a structured grid is constructed). 
\end{tipbox}
%
The last two numbers represent the coordinates of a given 
latitude and longitude, respectively. Note again how these 
information can be directly accessed through the object 
\inltc{grid}. 
Also, for retrieving a given latitude coordinate it is only 
necessary to specify one index that refers to that particular 
latitude (see line 20). On the other hand, for a given longitude 
we need to provide both the index of the latitude and the index 
of the longitude, since the longitude may depend on the latitude 
(see line 23).

You can now play with line 9 to generate 
different types of global structured grid using the keys introduced 
at the beginning of this section!



\section{Unstructured Grids}
Coming soon ...
