\section{The generated program}

This section introduces the Program. It explains about the data structures of the Program, outlines its structure in modules and summarizes the operations of each module. The section provides deeper understanding of the simulation implementation, and serves as a reference for building the Generator.

\subsection{Data structures}

\begin{figure}[ht]
%\begin{center}
\epsfig{file=content/diagrams/fortran_datastruct.ps,width=17cm}
%\end{center}
\caption{A diagram of the generated data structures.}
\label{fig: f_struct}
\end{figure}

Figure~\ref{fig: f_struct} shows the data structures used in the generated program. The \textit{variable\_int} and \textit{variable\_real} can represent both data variables and parameters. Each instance corresponds for example to one $alpha_{32}$ or $x_{31,4}$. A \textit{variables} instance represents a repetitive structure of the model, for example $alpha$ and $x$. The \textit{one\_dim} and \textit{two\_dim} are used for one-dimensional and two-dimensional variable structures, respectively.

In the case that a variable comes from data that has missing values in it, the \textit{one\_dim\_missing} or \textit{two\_dim\_missing}-index array contains the indices of the missing data, which are then treated as parameters.

The fields \textit{update\_count} and \textit{updates\_wanted} are included only if the user has chosen the random update strategy. (It is partially implemented, see chapter \ref{development})

If the model has a spatial structure, it is represented with the help of the \textit{spatial} array; this array has as many rows as the spatial structure has elements, and as many columns as is the greatest number of neighbours in the structure plus one. One row represents one spatial element. The first column of each row contains the number of neighbours that particular element has; the rest contain the indices of the neighbours.

\newpage
\subsection{Modules}
\label{moduleproposal}

% kuva
\begin{figure}[ht]
%\begin{center}
\epsfig{file=content/diagrams/fortran_modules.ps,width=17cm}
%\end{center}
\caption{A diagram of the generated modules and their subroutines.}
\label{fig: fmodules}
\end{figure}


Figure~\ref{fig: fmodules} illustrates the division of the generated program into modules. Each module is placed in its own source file, which are indicated in the upper right corners. 

For each subroutine and function the following information is included:
\begin{itemize}
\item \textit{Subroutine/function name}: The name of the subroutine or the function in the program.
\item \textit{Description}: What the subroutine or the function is meant to do.
\item \textit{Parameters}: The names, types and intents (IN, OUT, INOUT) of the parameters.
\end{itemize}

This information should suffice for the implementation of the Generator and allow for quicker understanding of the prototype code and the final generated program structure.

\subsubsection{Module proposal}

\begin{tabular}[]{| l p{10cm} |}
\hline
Subroutine name: & generate\_int\\
& \\
Description: & Generates a buffer of new proposals for a given variable by its name.\\
& \\
Parameters: & CHARACTER(LEN=*), INTENT(IN) :: name \newline INTEGER, DIMENSION(:), INTENT(OUT) :: buffer
	
	\begin{enumerate}
		\item
			name: \newline
				\textit{On entry:} The name of the variable to generate proposals for,
					e. g. $alpha$
	 \item
	 		buffer: \newline
	 			\textit{On exit:} The buffer filled with new proposals from the variable's proposal distribution.
	 			
	\end{enumerate}

\\
\hline
\end{tabular}
\vspace{.5cm}

\begin{tabular}[]{| l p{10cm} |}
\hline
Subroutine name: & generate\_real\\
& \\
Description: & Generates a buffer of new proposals for a given variable by its name.\\
& \\
Parameters: & CHARACTER(LEN=*), INTENT(IN) :: name \newline REAL, DIMENSION(:), INTENT(OUT) :: buffer
	
	\begin{enumerate}
		\item
			name: \newline
				\textit{On entry:} The name of the variable to generate proposals for,
					e. g. $alpha$
	 \item
	 		buffer: \newline
	 			\textit{On exit:} The buffer filled with new proposals from the variable's proposal distribution.
	 			
	\end{enumerate}

\\
\hline
\end{tabular}
\vspace{.5cm}


\subsubsection{Module input}
\label{moduleinput}

\begin{tabular}[]{| l p{10cm} |}
\hline
Subroutine name: & read\_data\\
& \\
Description: & Reads the data from data files into the data structure defined in figure~\ref{fig: f_struct}.\\
& \\
Parameters: & The variables found in the model, for example: \newline
TYPE(variables\_real), INTENT(INOUT) :: alpha \newline
TYPE(variables\_int), INTENT(INOUT) :: beta \newline
TYPE(variables\_int), INTENT(INOUT) :: x \newline
TYPE(variables\_int), INTENT(INOUT) :: obs \newline
Note that the parameters depend on the model in use.

\begin{enumerate}
		\item
			Each TYPE(variables\_...): \newline
				\textit{On entry:} The data structure describing the corresponding variable in the model
				\newline
				\textit{On exit:} The same except the \textit{is\_data} and \textit{value} fields are set.
	 			
\end{enumerate} 
\\
\hline
\end{tabular}
\vspace{.5cm}

\begin{tabular}[]{| l p{10cm} |}
\hline
Subroutine name: & set\_initial\_values\\
& \\
Description: & This subroutine reads the initial values from a data file into the data structure defined in figure~\ref{fig: f_struct}.\\
& \\
Parameters: & The variables found in the model, for example: \newline
TYPE(variables\_real), INTENT(INOUT) :: alpha \newline
TYPE(variables\_int), INTENT(INOUT) :: beta \newline
TYPE(variables\_int), INTENT(INOUT) :: x \newline
TYPE(variables\_int), INTENT(INOUT) :: obs \newline
Note that the parameters depend on the model in use.

\begin{enumerate}
		\item
			Each TYPE(variables\_...): \newline
				\textit{On entry:} The data structure describing the corresponding variable in the model
				\newline
				\textit{On exit:} The same except the \textit{value} fields are set corresponding the initial values.
	 			
\end{enumerate} 
\\
\hline
\end{tabular}
\vspace{.5cm}

\begin{tabular}[]{| l p{10cm} |}
\hline
Subroutine name: & set\_spatial\\
& \\
Description: & This subroutine reads the adjacency matrix from a file and initializes the corresponding data structure.\\
& \\
Parameters: & The structure defining spatial relationships, for example: \newline
INTEGER, DIMENSION(300, 5), INTENT(IN) :: spatial \newline
Note that the parameters depend on the model in use.

\begin{enumerate}
		\item
			INTEGER, DIMENSION(...) :: spatial: \newline
				\textit{On entry:} The data structure describing the spatial relationships
				\newline
				\textit{On exit:} The data structure correctly initialized. That is, spatial(i, 1) defines how many neighbours unit i (for example square i) has and spatial(i, 2) ... define the indices of the neighbours.
	 			
\end{enumerate} 
\\
\hline
\end{tabular}

\subsubsection{Module output}
\label{moduleoutput}

\begin{tabular}[]{| l p{10cm} |}
\hline
Subroutine name: & write\_output\\
& \\
Description: & This subroutine writes the output of one iteration into the output file. The file is opened and closed in the main program.\\
& \\
Parameters: & The variables found in the model, for example: \newline
TYPE(variables\_real), INTENT(IN) :: alpha \newline
TYPE(variables\_int), INTENT(IN) :: beta \newline
TYPE(variables\_int), INTENT(IN) :: x \newline
TYPE(variables\_int), INTENT(IN) :: obs \newline
Note that the parameters depend on the model in use.

\begin{enumerate}
		\item
			Each TYPE(variables\_...): \newline
				\textit{On entry:} The data structure describing the corresponding variable in the model	 			
\end{enumerate} 
\\
\hline
\end{tabular}
\vspace{.5cm}

\begin{tabular}[]{| l p{10cm} |}
\hline
Subroutine name: & write\_summary\\
& \\
Description: & This subroutine writes the summary of the simulation into a summary output file. The summary includes the number of updates and successful changes for each parameter.\\
& \\
Parameters: & The variables found in the model, for example: \newline
TYPE(variables\_real), INTENT(IN) :: alpha \newline
TYPE(variables\_int), INTENT(IN) :: beta \newline
TYPE(variables\_int), INTENT(IN) :: x \newline
TYPE(variables\_int), INTENT(IN) :: obs \newline
Note that the parameters depend on the model in use.

\begin{enumerate}
		\item
			Each TYPE(variables\_...): \newline
				\textit{On entry:} The data structure describing the corresponding variable in the model	 			
\end{enumerate} 
\\
\hline
\end{tabular}
\vspace{.5cm}

\subsubsection{Program main}
\label{modulemain}

\begin{tabular}[]{| l p{10cm} |}
\hline
Program name: & main\\
& \\
Description: & This is the main program which performs the simulation by using the subroutines described below.\\
\hline
\end{tabular}
\vspace{.5cm}

\begin{tabular}[]{| l p{10cm} |}
\hline
Subroutine name: & random\_init\\
& \\
Description: & This subroutine initializes the NAG random number generator.\\
& \\
Generating: & This subroutine is completely static so no information is needed.
\\
\hline
\end{tabular}
\vspace{.5cm}

\begin{tabular}[]{| l p{10cm} |}
\hline
Subroutine name: & update\_all\\
& \\
Description: & This subroutine updates each parameter once. It occurs in the generated program if and only if the user has chosen the sequential update strategy.\\
& \\
Parameters: & The variables found in the model, for example: \newline
TYPE(variables\_real), INTENT(INOUT) :: alpha \newline
TYPE(variables\_int), INTENT(INOUT) :: beta \newline
TYPE(variables\_int), INTENT(INOUT) :: x \newline
TYPE(variables\_int), INTENT(INOUT) :: obs \newline
Note that the parameters depend on the model in use.

\begin{enumerate}
		\item
			Each TYPE(variables\_...): \newline
				\textit{On entry:} The data structure describing the corresponding variable in the model
				\newline
				\textit{On exit:} The same except the \textit{value} fields are updated as the next iteration is performed.
		
	 			
\end{enumerate} 
\\
\hline
\end{tabular}
\vspace{.5cm}

\begin{tabular}[]{| l p{10cm} |}
\hline
Subroutine name: & set\_functional\\
& \\
Description: & This subroutine sets the values of functional variables before the simulation.\\
& \\
Parameters: & The variables found in the model, for example: \newline
TYPE(variables\_real), INTENT(INOUT) :: alpha \newline
TYPE(variables\_int), INTENT(INOUT) :: beta \newline
TYPE(variables\_int), INTENT(INOUT) :: x \newline
TYPE(variables\_int), INTENT(INOUT) :: obs \newline
Note that the parameters depend on the model in use.

\begin{enumerate}
		\item
			Each TYPE(variables\_...): \newline
				\textit{On entry:} The data structure describing the corresponding variable in the model
				\newline
				\textit{On exit:} The same except the \textit{value} fields of functional variables are updated.
		
	 			
\end{enumerate} 
\\
\hline
\end{tabular}
\vspace{.5cm}

%\begin{tabular}[]{| l p{10cm} |}
%\hline
%Subroutine name: & update\_one\\
%& \\
%Description: & This subroutine updates one parameter decided at random. It occurs in the generated program if and only if the user has chosen the random update strategy.\\
%& \\
%Parameters: & The variables found in the model and the structure defining spatial relationships, for example: \newline
%TYPE(variables\_real), INTENT(INOUT) :: alpha \newline
%TYPE(variables\_int), INTENT(INOUT) :: beta \newline
%TYPE(variables\_int), INTENT(INOUT) :: x \newline
%TYPE(variables\_int), INTENT(INOUT) :: obs \newline
%INTEGER, DIMENSION(300, 5), INTENT(IN) :: spatial \newline
%Note that the parameters depend on the model in use.
%
%INTEGER :: INTENT(INOUT) :: parameters\_achieved
%
%\begin{enumerate}
%		\item
%			Each TYPE(variables\_...): \newline
%				\textit{On entry:} The data structure describing the corresponding variable in the model
%				\newline
%				\textit{On exit:} The same except the \textit{value} fields are updated as the next iteration is performed
%				
%				
%    \item
%			INTEGER, DIMENSION(...) :: spatial: \newline
%				\textit{On entry:} The data structure describing the spatial relationships
%	
%		\item
%			parameters\_achieved: \newline
%				\textit{On entry:} The number of the parameters which have achieved their updates\_wanted count
%				\newline
%				\textit{On exit:} The number of the parameters which have achieved their updates\_wanted count
%	 			
%\end{enumerate} 
%\\
%& \\
%Generating: & 
%\begin{itemize}
%\item The names of the parameters and whether they are one-dimensional or two-dimensional
%\item The loop lengths, that is, how many different entities (birds, squares etc.) we have
%\item The proposal strategy (fixed or random walk) for each parameter
%\item The formula of the acceptance probability for each parameter (which variables depend on it and which parameter depend on it and what distributions define the dependencies)
%\item The proposal distributions for each parameter
%\item If the model is spatial: the maximum number of neighbours
%\end{itemize}

%\\
%\hline
%\end{tabular}
%\vspace{.5cm}


%\begin{tabular}[]{| l p{10cm} |}
%\hline
%Subroutine name: & \\
%& \\
%Description: & \\
%& \\
%Parameters: & ...\\
%& \\
%Generating: & \\
%\hline
%\end{tabular}
%\vspace{.5cm}