
\newpage

\section{Data structures}

\begin{figure}[ht]
%\begin{center}
\epsfig{file=content/diagrams/classes.ps,width=17cm}
%\end{center}
\caption{A diagram of the generator class structure.}
\label{fig: Generator}
\end{figure}


\subsection{Variable}

A number of variables are defined in the model file. These variables are represented by Variable objects. One Variable object describes one variable defined in the file. Equations and distributions in the model file define dependencies which are used to link the objects. Some of the fields are filled in after the reading of simulation parameter files, for example the proposal distribution. Distributions are saved in the Variable objects as Distribution objects. Equations are saved in the Variable objects as Equation objects. A Variable object can have either a distribution (stochastic) or an equation (functional). Both options have their own constructors.

\subsubsection{Fields of Variable}

\begin{tabular}[]{| p{5.5cm} | p{3cm} | p{7.5cm} |}
\hline
\textbf{Field name}&\textbf{Type}&\textbf{Description} \\
\hline
name & String & The name of the variable. \\
\hline
belongsTo & Entity & The Entity the variable is associated with, or Null if it isn't associated with any entity. \\
\hline
affects & LinkedList <Variable> & Pointers to each Variable which this Variable affects. \\
\hline
depends & LinkedList <Variable> & Pointers to each Variable of which this Variable depends on. \\
\hline
data & boolean & True if the variable is data, otherwise False. \\
\hline
column & int & The column the variable is found in if the variable is data. \\
\hline
functional & boolean & True if the variable is functional, False if it's stochastical. \\
\hline
equation & Equation & The equation for the variable if the variable is functional, otherwise Null. \\
\hline
distribution & Distribution & The Distribution for the variable if the variable is stochastic, otherwise Null. \\
\hline
proposal & Distribution & The proposal distribution of the variable. \\
\hline
missingValues & int & The number of missing values if the variable is data. \\
\hline
algorithm & String & The algorithm that is used for updating the variable. The program will use only one algorithm, so this field is needed only if someone expands the program to use other algorithms. \\
\hline
proposalStrategy & String & The proposal strategy used for the variable. \\
\hline
typeInteger & boolean & True if the variable is an integer, False if it's a double. \\
\hline
updates & int & The number of minimum updates for the variable. \\
\hline
printed & boolean & True if the variable is printed during the simulation, false otherwise. \\
\hline
\end{tabular}

\subsubsection{Operations of Variable}

\begin{tabular}[]{| p{5.5cm} | p{3cm} | p{7.5cm} |}
\hline
\textbf{Operation}&\textbf{Return type}&\textbf{Description} \\
\hline
Variable(Entity belongsTo, int column, boolean data, String name, distribution Distribution) & - & Constructor for a Variable object.\\
\hline
Variable(Entity belongsTo, int column, boolean data, String name, Equation equation) & - & Constructor for a Variable object.\\\hline
Variable() & - & Constructor for a Variable object.\\
\hline
getAffectsList() & LinkedList <Variable> & Returns a list of all Variables which this Variable affects.\\
\hline
addAffected(Variable variable) & void & Adds a Variable to affects list.\\
\hline
getDependenceList() & LinkedList <Variable> & Returns a list of all Variables which depend on this Variable.\\
\hline
addDependence(Variable variable) & void & Adds a Variable to dependence list.\\
\hline
getAlgorithm() & String & Returns the algorithm used to update this Variable.\\
\hline
setAlgorithm(String algorithm) & void & Sets the algorithm used to update this Variable.\\
\hline
getColumn() & int & Returns the column of a data file from which this Variable is found.\\
\hline
setColumn(int column) & void & Sets the column of a data file from which this Variable is found.\\
\hline
isData() & boolean & Returns true if Variable comes from data, false otherwise.\\
\hline
setData(boolean data) & void & Sets the attribute describing whether the Variable comes from data.\\
\hline
getEquation() & Equation & Returns an Equation object if the Variable is functional, null is returned otherwise.\\
\hline
setEquation(Equation equation) & void & Set an Equation object for the Variable is functional. \\
\hline
getDistribution() & Distribution & Returns a Distribution object if the Variable is stochastic, null is returned otherwise.\\
\hline
setDistribution(Distribution distribution) & void & Sets a Distribution object for the Variable.\\
\hline
isFunctional() & boolean & Returns true if the Variable is functional, false otherwise.\\
\hline
setFunctional(boolean) & boolean & Sets the attribute describing whether the Variable is functional. \\
\hline
getProposal() & Distribution & Returns Variable's proposal distribution.\\
\hline
setProposal(Distribution proposal) & void & Sets a proposal distribution to the Variable.\\
\hline
getStrategy() & String & Returns proposal strategy.\\
\hline
setStrategy(String strategy) & void & Sets a proposal strategy.\\
\hline
getUpdates() & int & Returns the number of updates.\\
\hline
setUpdates(int updates) & void & Sets the number of updates.\\
\hline
getMissingValueCount() & int & Returns the count of missing values in data.\\
\hline
incrementMissingValues() & void & Increases missing values by one.\\
\hline
\end{tabular}


\begin{tabular}[]{| p{5.5cm} | p{3cm} | p{7.5cm} |}
\hline
isInteger() & boolean & Returns true if the Variable is an integer, false otherwise.\\
\hline
setType(boolean typeInteger) & void & Sets the type of the Variable object. \\
\hline
getEntity() & Entity & Returns the Entity object the Variable belongs to or null if the variable is global.\\
\hline
setEntity(Entity entity) & void & Sets the Entity object the Variable belongs to. \\
\hline
setPrinted() & void & Sets the Variable to be printed.\\
\hline
isPrinted() & boolean & Returns true if the variable needs to be printed, false otherwise.\\
\hline
isOk() & boolean & Checks that all necessary fields are set. \\
\hline
\end{tabular}



\subsection{Entity}

A number of structures are defined in the model file. A structure can link a number of variables, defining the indexing and the data file(s) used. An Entity object is constructed for each structure. Entity objects are used when correct indexing for variables is computed. The data file names are also saved in the objects.

\subsubsection{Fields of Entity}

\begin{tabular}[]{| p{5.5cm} | p{3cm} | p{7.5cm} |}
\hline
\textbf{Field name}&\textbf{Type}&\textbf{Description}\\
\hline
dataFile & String & The name of the file where the data related to the entity is found. Null if the the entity is not related to data. \\
\hline
isMatrix & boolean & True if the data is in matrix format, otherwise false. \\
\hline
name & String & The name of the Entity. \\
\hline
size & int & The number of entities of this type. \\
\hline
spatialMatrixFile & String & The name of the file where the spatial matrix is found. Null if the entity is not spatial. \\
\hline
variableList & LinkedList <Variable> & The list of Variables related to the Entity. \\
\hline
xCoordinateString & String & The name of the Entity that the horizontal dimension in the spatial matrix represents. Null if the entity is not spatial. \\
\hline
yCoordinateString & String & The name of the Entity that the vertical dimension in the spatial matrix represents. Null if the entity is not spatial. \\
\hline
xCoordinate & Entity & The Entity that the horizontal dimension in the spatial matrix represents. Null if the entity is not spatial. \\
\hline
yCoordinate & Entity & The Entity that the vertical dimension in the spatial matrix represents. Null if the Entity is not spatial. \\
\hline
\end{tabular}

\subsubsection{Operations of Entity}

\begin{tabular}[]{| p{5.5cm} | p{3cm} | p{7.5cm} |}
\hline
\textbf{Operation}&\textbf{Return type}&\textbf{Description} \\
\hline
Entity(String name, String spatialMatrix, String xCoordinateString, String yCoordinateString) & - & Constructor for an Entity object.\\
\hline
Entity() & - & Constructor for an Entity object.\\
\hline
addVariable(Variable variable) & void & Adds a Variable object to the variable list.\\
\hline
getVariableList() & LinkedList <Variable> & Returns the variable list.\\
\hline
setName(String name) & void & Sets the name of the variable. \\
\hline
setSize(int size) & void & Sets the size of the object. This is the number of lines in the data file.\\
\hline
getSize() & int & Returns the size of the object.\\
\hline
getDataFile() & String & Returns the name of the data file.\\
\hline
isMatrix() & boolean & Returns true if the Entity combines two other Entities, and thus is a matrix.\\
\hline
setMatrix(boolean isMatrix) & void & Sets the isMatrix attribute of the entity.\\
\hline
getSpatialMatrixFile() & String & Returns the file name of spatial dependency matrix. Null is returned if there is no matrix.\\
\hline
setSpatialMatrixFile(String spatialMatrixFile) & void & Sets the name of the spatial matrix file.\\
\hline
getXCoordinate() & Entity & Returns the horizontal dimension Entity. Null is returned if the Entity is not a matrix.\\
\hline
setXCoordinate(Entity XCoordinate) & void & Sets the horizontal dimension Entity.\\
\hline
getYCoordinate() & Entity & Returns the vertical dimension Entity. Null is returned if the Entity is not a matrix.\\
\hline
setYCoordinate(Entity YCoordinate) & void & Sets the vertical dimension Entity.\\
\hline
link(HashMap <String, Entity> mapper) & void & Links the Entity object to other Entity objects.\\
\hline
\end{tabular}   

\newpage

\subsection{ComputationalModel}

\begin{figure}[ht]
%\begin{center}
\epsfig{file=content/diagrams/main_structure.ps,width=17cm}
%\end{center}
\caption{ComputationalModel and its relationships.}
\label{fig: ComputationalModel}
\end{figure}

The Parser returns a ComputationalModel object to the generator. The object has all the needed information to construct a working Fortran program which computes the given problem.

\subsubsection{Fields of ComputationalModel}

\begin{tabular}[]{| p{5.5cm} | p{2cm} | p{7.5cm} |}
\hline
\textbf{Field name}&\textbf{Type}&\textbf{Description}\\
\hline
iterations & int & The number of total iterations. This attribute is valid only if the update strategy is sequential. \\
\hline
burnIn & int & The number of iterations the program does before the printing of variables starts. \\
\hline
thinning & int & The number of iterations between the printing of variables. \\
\hline
updateStrategy & String & The update strategy used: sequential or random. \\
\hline
variableList & LinkedList <Variable> & A linked list of all global Variable objects. \\
\hline
entityList & LinkedList <Entity> & A linked list of all Entity objects. \\
\hline
entityMapper & HashMap <String, Entity> & A collection which combines Entity objects and their names. \\
\hline
variableMapper & HashMap <String, Variable> & A collection which combines all global Variable objects and their names. \\
\hline
modelFile & String & The file name of the model description file. \\
\hline
\end{tabular}

\subsubsection{Operations of ComputationalModel}

\begin{tabular}[]{| p{5.5cm} | p{2cm} | p{7.5cm} |}
\hline
\textbf{Operation}&\textbf{Return type}&\textbf{Description} \\
\hline
ComputationalModel(int iterations, int burnIn, int thinning, String updateStrategy, LinkedList <Variable> variableList, LinkedList <Entity> entityList, HashMap <String, Entity> entityMapper, 
HashMap <String, Variable> variableMapper, String modelFile) & - & Constructor for a ComputationalModel object. \\
\hline
getIterations() & int & Returns the total iterations, if specified. If the update strategy is random, this definition is not appropriate and this method returns -1. \\
\hline
getBurnIn() & int & Returns the length of the burn-in period. \\
\hline
getThinning() & int & Returns the thinning. \\
\hline
getUpdateStrategy() & String & Returns the update strategy. \\
\hline
getVariableList() & LinkedList <Variable> & Returns the linked list of all global Variable objects. \\
\hline
getEntityList() & LinkedList <Entity> & Returns the linked list of all Entity objects. \\
\hline
getEntityMapper() & HashMap <String, Entity> & Returns the HashMap collection which combines all Entity objects and their names. \\
\hline
getVariableMapper() & HashMap <String, Variable> & Returns the HashMap collection which combines all Variable objects and their names. \\
\hline
getModelFile() & String & Returns the name of the model description file. \\
\hline
\end{tabular}

\subsection{Equation}

An Equation is constructed for each functional variable. All variables in the functional variable's equation and the equation itself are saved in this Equation object.

\subsubsection{Fields of Equation}

\begin{tabular}[]{| p{5.5cm} | p{2cm} | p{7.5cm} |}
\hline
\textbf{Field name}&\textbf{Type}&\textbf{Description}\\
\hline
parameterString & String[] & An array of all variables in a equation. This field is used to store the variables before the linking. \\
\hline
parameters & Variable[] & An array of all variables in a equation. This field is used to store the variables after the linking.\\
\hline
equation & String & The equation of the object. \\
\hline
startingIndex & int[][] & Matrix of starting positions of all the variables in the equation. \\
\hline
\end{tabular}

\subsubsection{Operations of Equation}

\begin{tabular}[]{| p{5.5cm} | p{2cm} | p{7.5cm} |}
\hline
\textbf{Operation}&\textbf{Return type}&\textbf{Description} \\
\hline
Equation(String equation, String[] parameterString, int[][] startingIndexMatrix & - & The constructor for Equation.\\
\hline
getEquation() & String & Returns the equation stored in the Equation. \\
\hline
getParameterString() & String[] & Returns an array of parameters as String. \\
\hline
setParameters(Variable[] parameters) & void & Sets the parameters (Variables) used in the equation. \\
\hline
getParameters() & Variable[] & Returns the array of parameters. \\
\hline
getStratingIndexMatrix() & int[][] & Returns the starting index matrix. \\
\hline
\end{tabular}

\newpage

\subsection{Distribution}

\begin{figure}[ht]
%\begin{center}
\epsfig{file=content/diagrams/distributions2.ps,width=17cm}
%\end{center}
\caption{A diagram of the Distribution structure.}
\label{fig: Distribution}
\end{figure}

The Distribution is an abstract class that provides a simple interface for accessing different distributions' proposal generation and frequency functions without knowing their specifics. Distribution is extended by classes UserDistribution, DiscreteUniformDistribution, BinomialDistribution, PoissonDistribution, ContinuousUniformDistribution and BetaDistribution.

\subsubsection{Fields of Distribution}

The fields of Distribution are outlined here.

\begin{tabular}[]{| p{5.5cm} | p{2cm} | p{7.5cm} |}
\hline
\textbf{Field name}&\textbf{Type}&\textbf{Description}\\
\hline
numberOfParameters & int & The number of parameters for the mathematical function of the distribution.\\
\hline
intParameter & int [numberOfParameters] & Contains the parameters of this Distribution that are fixed integers.\\
\hline
realParameter & double [numberOfParameters] & Contains parameters of this Distribution that are fixed real numbers.\\
\hline
variableParameter & Variable [numberOfParameters] & Stores the parameters that must be referenced from Variable instances.\\
\hline
parameterType & int [numberOfParameters] & Contains a map of the parameter types that is used to index the different type parameter arrays in correct order. Acceptable values are: 0 = integer, 1 = double, 2 = Variable.\\
\hline
parameterString & String [numberOfParameters] & Contains the raw parsed parameter Strings that are used to build the links to the actual parameters according to their names.\\
\hline
\end{tabular}



\subsubsection{Operations of Distribution}

This section introduces the operations of Distribution.

\begin{tabular}[]{| p{5.5cm} | p{2cm} | p{7.5cm} |}
\hline
\textbf{Operation}&\textbf{Return type}&\textbf{Description} \\
\hline
getNumberOfParameters() & int & returns the value of \textit{numberOfParameters}.\\
\hline
isInteger(int index) & boolean & Returns \textit{true} if the parameter reference at \textit{index} is to be an INTEGER in the Program to be generated, otherwise returns \textit{false}.\\
\hline
getParameter(int index) & Object & Returns the parameter at \textit{index}.\\
\hline
setParameter(int index, int parameter) & void & sets \textit{parameter} into \textit{index} of \textit{intParameter}, and updates \textit{parameterType} accordingly.\\
\hline
setParameter(int index, double parameter) & void &  sets \textit{parameter} into \textit{index} of \textit{realParameter}, and updates \textit{parameterType} accordingly.\\
\hline
setParameter(int index, Variable parameter) & void &  sets \textit{parameter} into \textit{index} of \textit{variableParameter}, and updates \textit{parameterType} accordingly.\\
\hline
getParameterString(int index) & String & Returns the parsed parameter String at \textit{index} of \textit{parameterString}\\
\hline
setParameterString(int index, String parameter) & void & Sets the parsed parameter String at \textit{index} of \textit{parameterString}\\
\hline
abstract getIntroduction() & String[] & Returns the introduction lines necessary for the distribution modules. This is an EXTERNAL definition.\\
\hline
abstract getGenCode(String[] parameters & String & Returns the Fortran call for the proposal generation subroutine for the distribution as a String[].\\
\hline
abstract getFreqCode(String[] parameters) & String parameters & Returns the Fortran call for the frequency subroutine for the distribution as a String[].\\
\hline
\end{tabular}


\subsection{DistributionSkeleton}

The DistributionSkeleton serves as a collection of information that DistributionFactory uses for constructing UserDefinedDistribition instances.

\subsubsection{Fields of DistributionSkeleton}

\begin{tabular}[]{| p{5.5cm} | p{2cm} | p{7.5cm} |}
\hline
\textbf{Field name}&\textbf{Type}&\textbf{Description}\\
\hline
numberOfParameters & int & The number of parameters for the mathematical function of the distribution.\\
\hline
typeOfParameters & boolean [numberOfParameters] & Contains the types of parameters of this skeleton of a user-defined distribution. The value of an index is \textit{true} if the parameter at the index in question should be an integer, otherwise it is \textit{false}.\\
\hline
hasFreqFunction() & boolean & \textit{true} iff the distribution in question has a frequency function, that is the user distributions file has the header \textit{name}\_freq and such a subroutine exists there.\\
\hline
hasGenFunction() & boolean & \textit{true} iff the distribution in question has a proposal generation function, that is the user distributions file has the header \textit{name}\_gen and such a subroutine exists there. Note that user generation subroutines are expected to generate an arrayful of proposals on a single invocation.\\
\hline
name & String & Contains the name of the distribution, this being the first part of the distribution's corresponding subroutine names mentioned above. \\
\hline
\end{tabular}

\subsubsection{Operations of DistributionSkeleton}

These operations allow for query of field values, only. Setting the field values is always done upon creation, see the constructor.

\begin{tabular}[]{| p{5.5cm} | p{2cm} | p{7.5cm} |}
\hline
\textbf{Operation}&\textbf{Return type}&\textbf{Description} \\
\hline
\textbf{DistributionSkeleton} (String name, int numberOfParameters, boolean[] typeOfParameters, boolean hasFreqFunction, boolean hasGenFunction)  & - & The constructor: creates a new DistributionSkeleton instance. This will be called after reading the user-defined distributions from the user distribution file, once for each such distribution name.\\
\hline
getName() & String & Returns the value of \textit{name}.\\
\hline
getNumberOfParameters() & int & returns the value of \textit{numberOfParameters}.\\
\hline
getTypeOfParameters() & boolean[] & Returns a reference to \textit{typeOfParameters} \\
\hline
hasFreqFunction() & boolean & Returns the value of \textit{hasFreqFunction} \\
\hline
hasGenFunction() & boolean & Returns the value of \textit{hasGenFunction} \\
\hline
\end{tabular}

\subsection{DistributionFactory}

The DistributionFactory stores information about the distributions, both user-defined and provided. It can be used to match a distribution name to its corresponding Distribution entity and create an instance of this for the linking of a Variable to other Variables via its Distribution.

\subsubsection{Fields of DistributionFactory}

\begin{tabular}[]{| p{5.5cm} | p{2cm} | p{7.5cm} |}
\hline
\textbf{Field name}&\textbf{Type}&\textbf{Description}\\
\hline
userDistributions & HashMap <String, DistributionSkeleton> & Contains a map of DistributionSkeletons that can be accessed by the distribution names.\\
\hline
\end{tabular}


\subsubsection{Operations of DistributionFactory}

The operations used for acquiring distributions for variables.

\begin{tabular}[]{| p{5.5cm} | p{2cm} | p{7.5cm} |}
\hline
\textbf{Operation}&\textbf{Return type}&\textbf{Description} \\
\hline
\textbf{DistributionFactory} (File distributionFile) & - & The constructor: associates the new instance with a given user-defined distributions file.\\
\hline
getDistribution(String name) & Distribution & Returns a reference to a newly created Distribution with the given \textit{name}, by first indexing the \textit{userDistributions} and then constructing a Distribution subclass from the information. \\
\hline
\end{tabular}

\subsection{UserDefinedDistribution}

UserDefinedDistribution is a subclass of Distribution. An UserDefinedDistribution object is constructed for each user given distribution.

\subsubsection{Fields of UserDefinedDistribution}

UserDefinedDistribution has the same fields as other Distribution class' subclasses have. It also has a field for a DistributionSkeleton object.

\subsubsection{Operations of UserDefinedDistribution}

The UserDefinedDistribution represents a non-standard distribution instance. It differs from Distribution only with its constructor.

\begin{tabular}[]{| p{5.5cm} | p{2cm} | p{7.5cm} |}
\hline
\textbf{Operation}&\textbf{Return type}&\textbf{Description} \\
\hline
\textbf{UserDefinedDistribution} (DistributionSkeleton userDistribution) & - & The constructor: creates a new instance according to the information in \textit{userDistribution}.\\
\hline
\end{tabular}
