
\documentclass[12pt]{amsart}
\usepackage{geometry} % see geometry.pdf on how to lay out the page. There's lots.
\usepackage{booktabs}
\usepackage{topcapt}
% \geometry{landscape} % rotated page geometry

% See the ``Article customise'' template for come common customisations
\newcommand{\code}[1]{{\tt #1}}


\title{Model Grid Design and Programming Notes}
\author{Greg Tucker}
\date{June 2013} % delete this line to display the current date

%%% BEGIN DOCUMENT
\begin{document}

\maketitle
%\tableofcontents

\section{ModelGrid General}

\subsection{Data structures for grid elements and connectivity}

\begin{table}[htbp]
   \centering
   \topcaption{Grid data structures} % requires the topcapt package
   \begin{tabular}{@{} lccc @{}} % Column formatting, @{} suppresses leading/trailing space
      \toprule
      
      %\cmidrule(r){1-2} % Partial rule. (r) trims the line a little bit on the right; (l) & (lr) also possible
      Name & Type$^1$ & Indexed by & Description \\
      \midrule
      node\_activecell & list  & nodes & ID of active cell, or None \\
      node\_status 	& NP & nodes & Boundary code \\
      node\_numinlink  & NP & nodes & Number of incoming links  \\
      node\_numoutlink  & NP & nodes & Number of outgoing links  \\
      node\_numactiveinlink  & NP & nodes & Number of incoming active links  \\
      node\_numactiveoutlink  & NP & nodes & Number of outgoing active links  \\
      node\_x & NP & nodes & $x$-coordinate \\
      node\_y & NP & nodes & $y$-coordinate \\
      node\_z & NP & nodes & $z$-coordinate \\
      node\_inlink\_matrix & NP2D & (note 2) & IDs of incoming links, or -1 \\
      node\_outlink\_matrix & NP2D &  (note 2) & IDs of outgoing links, or -1 \\
      node\_active\_inlink\_matrix & NP2D &  (note 2) & IDs of incoming active links, or -1 \\
      node\_active\_outlink\_matrix & NP2D &  (note 2) & IDs of outgoing active links, or -1 \\
      cell\_node & list & cells & ID of associated node \\
      activecell\_node & list & active cells & ID of associated node \\
      active\_cell\_areas & ? & ? & Surface area of cell \\
      link\_fromnode & NP & links & ID of ``from'' node \\
      link\_tonode & NP & links & ID of ``to'' node \\
      link\_length & NP & links & Planview length \\
      link\_face & list & links & ID of face, or None \\
      activelink\_fromnode & NP & links & ID of ``from'' node \\
      activelink\_tonode & NP & links & ID of ``to'' node \\
      \bottomrule
      \multicolumn{4}{l}{$^1$ NP = 1D Numpy array; NP2D = 2D Numpy array} \\
      \multicolumn{4}{l}{$^2$ No.\ nodes by max no.\ in/out links (see text)} \\
   \end{tabular}
   %\caption{Remember, \emph{never} use vertical lines in tables.}
   \label{tab:formulas}
\end{table}



\section{RasterModelGrid}

\subsection{Grid Element Numbers and Numbering}

A basic raster model grid consists of a rectangular matrix of nodes with $R$ rows and $C$ columns. Here I list the numbers and numbering schemes for the various elements in the grid, for the default case in which all perimeter nodes are open boundaries, and all interior nodes and all cells are active. Note that grids with different boundary conditions will have different numbers of active links/edges and active faces. 

As a template example, I also list the numbers of elements for a 5-column by 4-row grid in two cases: all open boundaries, and only bottom and right boundaries open.

% Requires the booktabs if the memoir class is not being used
\begin{table}[htbp]
   \centering
   \topcaption{Formulas for numbers of elements in a rectangular grid with $R$ rows and $C$ columns} % requires the topcapt package
   \begin{tabular}{@{} lccc @{}} % Column formatting, @{} suppresses leading/trailing space
      \toprule
      %\multicolumn{2}{c}{Item} \\
      %\cmidrule(r){1-2} % Partial rule. (r) trims the line a little bit on the right; (l) & (lr) also possible
      Element & Formula & $4\times 5$ Grid & $4\times 5$ Grid \\
       &  & (all open) & (right, bottom) \\
      \midrule
      Nodes         & $RC$ & 20 & 20 \\
      Cells           & $(R-2)(C-2)$ & 6 & 6 \\
      Active cells & $(R-2)(C-2)$ & 6 & 6 \\
      Links           & $C(R-1)+R(C-1)$ & 31 & 31 \\
      Active links & $(R-1)(C-2)+(R-2)(C-1)$ & 17 & 12 \\
      Corners      & $(R-1)(C-1)$ & 12 & 12 \\
      Faces         & $(R-1)(C-2)+(R-2)(C-1)$ & 17 & 17 \\
      Active faces & $(R-1)(C-2)+(R-2)(C-1)$ & 17 & 12 \\
      \bottomrule
   \end{tabular}
   %\caption{Remember, \emph{never} use vertical lines in tables.}
   \label{tab:formulas}
\end{table}

By default, the numbering scheme for a raster model grid works as follows. Nodes are numbered starting from the lower left and advancing by columns first, then rows. So, a five-column by four-row grid would have nodes numbered as follows:
\newpage
\begin{verbatim}
        # 15------16------17------18------19
        #  |       |       |       |       |
        #  |       |       |       |       |
        #  |       |       |       |       |
        # 10------11------12------13------14
        #  |       |       |       |       |
        #  |       |       |       |       |   
        #  |       |       |       |       |
        #  5-------6-------7-------8-------9
        #  |       |       |       |       |
        #  |       |       |       |       |
        #  |       |       |       |       |
        #  0-------1-------2-------3-------4
\end{verbatim}

Cell numbering follows the same scheme. However, there are no cells associated with the perimeter nodes. In the four-row, five-column example, there are 20 nodes but only six cells. The numbering of the cells is as shown here:
\begin{verbatim}
        # |-------|-------|-------|
        # |       |       |       |
        # |   3   |   4   |   5   |
        # |       |       |       |
        # |-------|-------|-------|
        # |       |       |       |
        # |   0   |   1   |   2   |
        # |       |       |       |
        # |-------|-------|-------|
\end{verbatim}
Note that in this diagram, the lines represent faces and the numbers coincide with nodes.

Links are numbered in the same basic ordering, but starting with all vertical links first, and then proceeding through all horizontal links. Here is an example of link numbering for a five-column by four-row grid:
\newpage
\begin{verbatim}
        #  *--27-->*--28-->*--29-->*--30-->*
        #  ^       ^       ^       ^       ^
        # 10      11      12      13      14
        #  |       |       |       |       |
        #  *--23-->*--24-->*--25-->*--26-->*
        #  ^       ^       ^       ^       ^
        #  5       6       7       8       9   
        #  |       |       |       |       |
        #  *--19-->*--20-->*--21-->*--22-->*
        #  ^       ^       ^       ^       ^
        #  0       1       2       3       4
        #  |       |       |       |       |
        #  *--15-->*--16-->*--17-->*--18-->*
\end{verbatim}
In the above diagram, the asterisks are nodes, the lines are links, and the \verb!^! and \verb!>! symbols are meant to indicate the direction of each link (up for vertical links, and to the right for horizontal links).

\subsection{Data structures for node-link connectivity}

There are two basic types of information we wish to store: information about the nodes connected to each link, and information about the links connected to each node.
The first of these is fairly straightforward. 
The nodes that form the ``from'' and ``to'' nodes for each are stored in two lists: \code{link\_fromnode} and \code{link\_tonode}. For example, the ID of the ``from'' node of link number 7 is stored in \code{link\_fromnode[7]}. 

Storing information about the links connected to 





%\section{Time tests}
%
%Comparing diffusion code with and without giving gradient or flux as arguments to gradient and flux divergence functions:
%
%20 x 30 grid without: 5.1, 4.9, 4.8, 4.9, 5.0 sec (avg 4.92)
%
%20 x 30 grid with: 4.8, 4.8, 4.9, 4.8, 4.8 sec (avg 4.82)
%%%% notes
%
%Using this alternative to gradient:
%
%        alarray = array(self.active_links)
%        lfna = array(self.link_fromnode)
%        ltna = array(self.link_tonode)
%        fromnodes = lfna[alarray]
%        tonodes = ltna[alarray]
%        sto = s[tonodes]
%        sfrom = s[fromnodes]
%        gradient = (sto-sfrom)/self.dx
%        
%        return gradient
%
%has timing: 3.3, 3.3, 3.4, 3.3, 3.3
%
%NOTES
%
%potential algos for activating/deactivating elements (changing boundary condition)
%
%(1) define based on nodes. an active link is one that connects either a pair of active cells, or an active and an open boundary cell.
%
%in this case, we'd have a function like:

%def makeListOfActiveLinks( active_link_list ):
%	
%	active_link_list = []
%	for link in range( 0, self.num_links ):
%		fromnode_status = self.node_status[self.link_fromnode[link]]
%		tonode_status = self.node_status[self.link_fromnode[link]]
%		if fromnode_status==INTERIOR and
%		  ( tonode_status==INTERIOR 
%		    or tonode_status==OPEN_BOUNDARY ):
%		     	add to list
%		elif tonode_status==INTERIOR and
%		  ( fromnode_status==INTERIOR 
%		    or fromnode_status==OPEN_BOUNDARY ):
%			add to list
			
(2) know the ID numbering scheme for links and set the appropriate ones

	
			
\end{document}