
This appendix describes the functions that are provided in the phaml\_example module and that must be maintained in any new modules.  The subroutines exist within the example module rather than the support module so that they can be modified or tweaked based on the specific problem.  PHAML provides many options to all function calls and this method allows the options to be different between modules if desired without affecting another module.

These are wrappers to ease the use of PHAML and to setup all initial conditions and make sure everything is properly handled with PHAML and the other modules needed.  Please see the guide for the native PHAML functions. \citep{phamldoc} 

\subsection{Main Module}\label{sec:libfuncmain}

\begin{itemize}
\item \textbf{phaml\_init} - This subroutine simply sets the needed variables for the usermod module to work.  It does not instantiate the phaml\_solution.
\item \textbf{phaml\_setup} - If doing a non-linear PDE problem then this initializes the phaml\_solution, creates the mesh, and sets the initial conditions.  To solve phaml\_nonlin\_evolve must be called.
\item \textbf{phaml\_evolve} - This is a single pass solve where the function assumes the problem is linear.  It creates the mesh, initializes PHAML, solves the problem, retrieves the solution, then closes PHAML.
\item \textbf{phaml\_nonlin\_evolve} - This subroutine assumes phaml\_setup has already been called and that the solution is incremental.  It copies the old solution then does another iteration and returns.
\item \textbf{phaml\_getsolution} - Given the phaml\_solution variable it simply returns the current solution at the node points of the GLIMMER-CISM model grid. 
\item \textbf{phaml\_close} - This destroys the phaml session variable as well as deallocates the variables used in usermod.
\end{itemize}

\subsection{PHAML Callbacks}\label{sec:libphamlcall}

This subsection lists the subroutines and functions that PHAML relies on and must be present in order for it to define the PDE and to find a solution.  Given the type of solution desired, many of them don't need to be used, but they must all still exist even if returning zero.  Please refer to the manual for more detailed descriptions, special circumstances, arguments, and examples.  \citep{phamldoc}

\begin{itemize}
\item \textbf{pdecoefs} - This subroutine returns the coefficient and right hand side of the PDE at the point (x,y). 
\item \textbf{bconds} - This subroutine returns the boundary conditions at the point (x,y).
\item \textbf{iconds} - This routine returns the initial condition for a time dependent problem at the point (x,y).
\item \textbf{trues} - This is the true solution of the differential equation at point (x,y), if known.
\item \textbf{truexs} - This is the x derivative of the true solution of the differential equation at point (x,y), if known.
\item \textbf{trueys} - This is the y derivative of the true solution of the differential equation at point (x,y), if known. 
\item \textbf{boundary\_point} -  This routine defines the boundary of the domain at the point (x,y) if no mesh was provided. 
\item \textbf{boundary\_npiece} - This routine gives the number of pieces in the boundary definition if no mesh was provided. 
\item \textbf{boundary\_param} - This routine gives the range of parameter values for each piece of the boundary if no mesh was provided.
\item \textbf{phaml\_integral\_kernel} - This is the identity function that PHAML requires and shouldn't need any modification.
\item \textbf{regularity} - Provides the \emph{a priori} knowledge about the singular nature of the solution if applicable.
\item \textbf{update\_usermod} - This routine updates the module variables by sending them from the master to the slave processes.  This function is very important for the simulation to work correctly, and the data formatting is addressed in more detail in section \ref{sec:libfuncuser}.

\end{itemize}
%\begin{table}[ht]
%\caption{PHAML PDE Callback Functions \cite{phamldoc}}
%\centering
%\begin{center}
%    \begin{tabular}{ | c | c |}
%    \hline
%    \multicolumn{2}{|c|}{PHAML PDE Functions}\\
%    \hline
%    Function Name & Description \\ \hline
%    pdecoefs & This subroutine returns the coefficient and right \\
%    &   hand side of the PDE at the point (x,y). \\ \hline
%    bconds & This subroutine returns the boundary conditions at the\\
%    &   point (x,y). \\ \hline
%    iconds & This routine returns the initial condition for a time\\
%    &   dependent problem at the point (x,y). \\ \hline
%    trues & This is the true solution of the differential equation\\
%    &   at point (x,y), if known.\\ \hline
%    truexs & This is the x derivative of the true solution of the \\
%    &   differential equation at point (x,y), if known. \\ \hline
%    trueys & This is the y derivative of the true solution of the \\
%    &   differential equation at point (x,y), if known. \\ \hline
%    boundary\_point &  This routine defines the boundary of the domain \\
%    &   at the point (x,y) if no mesh was provided. \\ \hline
%    boundary\_npiece & This routine gives the number of pieces in the boundary\\
%    &   definition if no mesh was provided. \\ \hline
%    boundary\_param & This routine gives the range of parameter values for\\
%    &   each piece of the boundary if no mesh was provided. \\ \hline
%    \end{tabular}
%\end{center}
%\end{table}

\subsection{Support Module}\label{sec:libfuncsupp}

These subroutines are independent of PHAML and are simply support functions needed by the various PHAML modules that can be created.  There is a possibility that some of them may need to be modified depending on a particular simulation need, but in general should be applicable to most situations.

\begin{itemize}
\item \textbf{is\_ice\_edge} - This function uses the mask to determine if a node is the last node on the glacier to have ice.  It does this by checking all four surrounding nodes to make sure at least one of them doesn't have ice. 
\item \textbf{get\_bmark} - This function returns the boundary marker required in the .poly file for edges.  Currently it uses the `mask' value, but can be changed depending on other needs.
\item \textbf{make\_ice\_poly\_file} - This subroutine generates the mesh file that PHAML loads by only using nodes that have ice as decided by the mask in CISM.  It uses the get\_bmark and is\_ice\_edge subroutines.  Once it writes out the .poly file it calls Triangle in order to process it for use by PHAML.  
\item \textbf{make\_full\_poly\_file} - This subroutine generates the mesh file that PHAML loads by using the full domain space.  A rectangular grid will always be output.  The function writes out the .poly file and then calls Triangle in order to process it for use by PHAML.  
\end{itemize}

\subsection{Usermod Module}\label{sec:libfuncuser}

The usermod module is a set of variables and routines that are used or might be used from within the PHAML callbacks.  Any data coming from GLIMMER-CISM would need to be set in one of these variables and then could be used in a callback.  All the data must be passed on to PHAML's slaves though the function `update\_usermod' that is in the set of PHAML callbacks.  These callbacks can be tricky and are explained further in section \ref{sec:libphamlcall}.  The usermod module is addressed in chapter \ref{ch:softintegration} section \ref{sec:ch4usermod}.

\subsubsection{The functions}

\begin{itemize}
\item \textbf{user\_init} - This function sets up the initial data for the usermod module.
\item \textbf{user\_close} - This function serves to call any closing subroutines or deallocate any user data that was initialized.
\item \textbf{array\_init} - Once the slaves have the data from user\_init, the array variables can be allocated and sent as well.  This function should be called from within update\_usermod.
\item \textbf{array\_close} - This is to deallocate the arrays used in the usermod function which had to be dynamically allocated.
\item \textbf{concat\_arrays} - Since the usermod requires all data be passed in one array it might be necessary to pass more than one, and it would be easy to lose track of them.  This function concatenates them together in a consistent fashion.
\item \textbf{split\_arrays} - This is the inverse function to concat\_arrays.  It will split an array back into the original two based on the length specified in the usermod data. 
\item \textbf{reshape\_array\_to\_one} - In order to pass data to the slaves in PHAML, all data must be passed in a single dimension array.  This function takes a two dimensional array and converts it to one dimension.
\item \textbf{reshape\_array\_to\_two} - This is the inverse function to reshape\_array\_to\_one.  It takes in the single dimension array and splits it back into two dimensions based on the model `nsn' and `ewn'.
\item \textbf{get\_xyarrays} - PHAML returns the solution in one long array, so this function returns two arrays with the corresponding node locations in absolute dimensions to pass to the phaml\_evaluate function.
\item \textbf{getew} - Given an x in absolute coordinates, this divides it by the `dew' and truncates it into an integer in order to return the nearest ew coordinate for the grid.
\item \textbf{getns} - Given a y in absolute coordinates, this divides it by the `dns' and truncates it into an integer in order to return the nearest ns coordinate for the grid.
\end{itemize}

\subsubsection{The variables}

\begin{itemize}
\item \textbf{gnsn} - The number of nodes in the north/south direction of the grid.
\item \textbf{gewn} - The number of nodes in the east/west direction of the grid.
\item \textbf{gdns} - The representative distance in meters between each node in the north / south direction. 
\item \textbf{gdew} - The representative distance in meters between each node in the east / west direction.
\item \textbf{num\_arrays} - The number of arrays needed to be passed via update\_usermod
\item \textbf{modnum} - The unique identifier (integer) for this module so that the correct callback functions will be used.
\end{itemize}
