\subsection{package PIANOS.datastructures}

This package contains the data structures of the software.

\Subsubsection{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). 

\newpage
\subsubsubsection{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 \textit{null} if it isn't associated with any entity. \\
\hline
affects & LinkedList <Variable> & Pointers to each Variable that this Variable affects. \\
\hline
depends & LinkedList <Variable> & Pointers to each Variable that this Variable depends on. \\
\hline
data & boolean & \textit{true} if the variable is data, otherwise \textit{false}. \\
\hline
column & int & The column the variable is found in if the variable is data. \\
\hline
functional & boolean & \textit{true} if the variable is functional, \textit{false} if it's stochastic. \\
\hline
equation & Equation & The equation for the variable if the variable is functional, otherwise \textit{null}. \\
\hline
distribution & Distribution & The Distribution for the variable if the variable is stochastic, otherwise \textit{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 & \textit{true} if the variable is an integer, \textit{false} if it's a double. \\
\hline
updates & int & The number of minimum updates for the variable. This field is not used since the random update strategy is not implemented.\\
\hline
printed & boolean & \textit{true} if the variable is printed during the simulation, \textit{false} otherwise. \\
\hline
spatial & boolean & \textit{true} if the variable is a functional variable with a spatial expression (SUM or COUNT), \textit{false} otherwise. \\
\hline
\end{tabular}

\newpage
\subsubsubsection{Operations of Variable}

\begin{tabular}[]{| p{5.5cm} | p{3cm} | p{7.5cm} |}
\hline
\textbf{Operation}&\textbf{Return type}&\textbf{Description} \\
\hline
Variable() & - & Constructor for a Variable object.\\
\hline
getAffectsList() & LinkedList <Variable> & Returns a list of all Variables that this Variable affects.\\
\hline
addAffected(Variable variable) & void & Adds a Variable to \textit{affects}.\\
\hline
getDependsList() & LinkedList <Variable> & Returns a list of all Variables that depend on this Variable.\\
\hline
addDependence(Variable variable) & void & Adds a Variable to \textit{depends}.\\
\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 in which this Variable is found.\\
\hline
setColumn(int column) & void & Sets the column of a data file in which this Variable is found.\\
\hline
isData() & boolean & Returns \textit{true} if this Variable comes from data, \textit{false} otherwise.\\
\hline
setData(boolean data) & void & Sets whether the Variable comes from data.\\
\hline
getEquation() & Equation & Returns the Variable's Equation if the Variable is functional, \textit{null} is returned otherwise.\\
\hline
setEquation(Equation equation) & void & Set the Equation for the Variable. \\
\hline
getDistribution() & Distribution & Returns a Distribution object if the Variable is stochastic, \textit{null} is returned otherwise.\\
\hline
setDistribution(Distribution distribution) & void & Sets the Distribution for the Variable.\\
\hline
isFunctional() & boolean & Returns \textit{true} if the Variable is functional, \textit{false} otherwise.\\
\hline
setFunctional(boolean funct) & void & Sets whether the Variable is functional. \\
\hline
isSpatial() & boolean & Returns \textit{true} if the Variable is spatial, \textit{false} otherwise.\\
\hline
setSpatial(boolean spatial) & void & Sets whether the Variable is spatial (functional and has a SUM(\&x) -style equation). \\
\hline
getName() & String & Returns the name of the variable.\\
\hline
setName(String) & void & Sets the name of the variable. \\
\hline
getProposal() & Distribution & Returns the variable's proposal distribution.\\
\hline
setProposal(Distribution proposal) & void & Sets the proposal distribution to the Variable.\\
\hline
\end{tabular}


\begin{tabular}[]{| p{5.5cm} | p{3cm} | p{7.5cm} |}
\hline
getStrategy() & String & Returns the variable's proposal strategy.\\
\hline
setStrategy(String strategy) & void & Sets the 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
isInteger() & boolean & Returns \textit{true} if the Variable is an integer, \textit{false} otherwise.\\
\hline
setType(boolean typeInteger) & void & Sets the type of the variable. \\
\hline
getEntity() & Entity & Returns the Entity the Variable belongs to or \textit{null} if the variable is global.\\
\hline
setEntity(Entity entity) & void & Sets the Entity that the Variable belongs to. \\
\hline
setPrinted() & void & Sets the Variable to be printed during simulation.\\
\hline
isPrinted() & boolean & Returns \textit{true} if the variable is printed during the simulation, \textit{false} otherwise.\\
\hline
isOk() & boolean & Checks that all necessary fields are set and that dependencies are sane. \\
\hline
\end{tabular}


\newpage
\Subsubsection{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.

\subsubsubsection{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. \textit{null} if the the entity is not related to data. \\
\hline
isMatrix & boolean & \textit{true} if the data is in matrix format, otherwise \textit{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 adjacency matrix is found. \textit{null} if the entity is not spatial. \\
\hline
variableList & LinkedList <Variable> & The list of Variables related to the Entity. \\
\hline
xCoordinate & Entity & The Entity that the horizontal dimension in the data matrix represents. \textit{null} if the entity is not an intersection of two entities. \\
\hline
yCoordinate & Entity & The Entity that the vertical dimension in the data matrix represents. \textit{null} if the Entity is not an intersection of two entities. \\
\hline
\end{tabular}

\newpage
\subsubsubsection{Operations of Entity}

\begin{tabular}[]{| p{5.5cm} | p{3cm} | p{7.5cm} |}
\hline
\textbf{Operation}&\textbf{Return type}&\textbf{Description} \\
\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 entity. \\
\hline
getName() & String & Returns the name of the entity. \\
\hline
setSize(int size) & void & Sets the size of this Entity. This is the number of lines in the data file.\\
\hline
getSize() & int & Returns the size of the object.\\
\hline
setLineLength(int lineLength) & void & Sets the line length.\\
\hline
getLineLength() & int & Returns the line length.\\
\hline
getDataFile() & String & Returns the name of the data file.\\
\hline
setDataFile(String dataFile) & void & Sets the name of the data file.\\
\hline
isMatrix() & boolean & Returns \textit{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 the adjacency matrix. \textit{null} is returned if there is no matrix.\\
\hline
setSpatialMatrixFile(String spatialMatrixFile) & void & Sets the name of the adjacency matrix file.\\
\hline
getXCoordinate() & Entity & Returns the horizontal dimension Entity. \textit{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. \textit{null} is returned if the Entity is not a matrix.\\
\hline
setYCoordinate(Entity YCoordinate) & void & Sets the vertical dimension Entity.\\
\hline
isSpatial() & boolean & Returns \textit{true} if the entity is spatial. \\
\hline
\end{tabular}   

\newpage

\Subsubsection{ComputationalModel}

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.

\subsubsubsection{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'. The random update strategy is not implemented\\
\hline
maxSpatialNeighbours & int & The maximum number of spatial neighbours in the simulation. \\
\hline
modelFile & String & The file name of the model description file. \\
\hline
initialValueFile & String & The file name of the initial value file. \\
\hline
outputFile & String & The file name of the output file. \\
\hline
summaryFile & String & The file name of the summary file. \\
\hline
lastValuesFileName & String & The file name of the last values file. \\
\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 Variables and their names. \\
\hline
topologicalVariableList & ArrayList <Variable> & A collection of all variables in topological order.\\
\hline
\end{tabular}

\newpage
\subsubsubsection{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
getNeighbourCount() & int & Returns the maximum number of spatial neighbours. \\
\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
getModelFileName() & String & Returns the name of the model description file. \\
\hline
getOutputFileName() & String & Returns the name of the output file. \\
\hline
getInitialFileName() & String & Returns the name of the initial value file. \\
\hline
getSummaryFileName() & String & Returns the name of the summary file. \\
\hline
getLastValuesFileName() & String & Returns the name of the last values file. \\
\hline
getTopologicalVariableList() & ArrayList <Variable> & Returns a topologically ordered collection of Variable objects. \\
\hline
\end{tabular}

\newpage
\Subsubsection{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.

\subsubsubsection{Fields of Equation}

\begin{tabular}[]{| p{5.5cm} | p{2cm} | p{7.5cm} |}
\hline
\textbf{Field name}&\textbf{Type}&\textbf{Description}\\
\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, broken down so that every index is either a single variable name or something else (so that each index can be matched against variable names and replaced with the final Fortran expression) \\
\hline
\end{tabular}

\subsubsubsection{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, Variable[] parameters) & - & The constructor for Equation.\\
\hline
getEquation() & String[] & Returns the equation stored in the Equation. \\
\hline
setParameters(Variable[] parameters) & void & Sets the parameters (Variables) used in the equation. \\
\hline
getParameters() & Variable[] & Returns the array of parameters. \\
\hline
setParameters(Variable parameter) & void & Sets \textit{Parameters} to be  \{\textit{parameter}\}. This is useful for
Equations with spatial expressions.
 \\
\hline
\end{tabular}

\newpage

\Subsubsection{Distribution}

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 UserDefinedDistribution, DiscreteUniformDistribution, BinomialDistribution, PoissonDistribution, ContinuousUniformDistribution and BetaDistribution.

\subsubsubsection{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}


\newpage
\subsubsubsection{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() & ArrayList<String> & Returns the introduction lines (EXTERNAL) necessary for using this distribution. \\
\hline
abstract getGenCode(String[] parameters & ArrayList<String> & Returns the Fortran call for the proposal generation subroutine for the distribution as a String[].\\
\hline
abstract getFreqCode(String[] parameters) & ArrayList<String> & Returns the Fortran call for the frequency subroutine for the distribution as a String[].\\
\hline
\end{tabular}

\newpage
\Subsubsection{DistributionSkeleton}

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

\subsubsubsection{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
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}

\newpage
\subsubsubsection{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
hasGenFunction() & boolean & Returns the value of \textit{hasGenFunction} \\
\hline
\end{tabular}

\Subsubsection{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}

\newpage
\subsubsubsection{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. Returns also internal Distributions such as BetaDistribution.\\
\hline
\end{tabular}

\Subsubsection{UserDefinedDistribution}

UserDefinedDistribution is a subclass of Distribution. A UserDefinedDistribution object is constructed for each user-defined distribution used in the model.

\subsubsubsection{Fields of UserDefinedDistribution}

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

\subsubsubsection{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}
