\chapter{Worker}
\label{chap:worker}

The worker in the GREAT-ER Model System implements the models. A worker
computes serialised simulations requested by the scheduler the worker is
connected to. To get the information needed for a simulation a worker 
reads a session and associated data from the data base. A worker does not write
to the database, simulation results are collected and written by the scheduler.

\section{Scheduler-Worker Network Protocol}
\label{sec:scheduler-worker-network-protocol}
This section describes the methods of the perspectives mentioned in 
\ref{sec:scheduler-worker-interface} the worker implements.

\subsection{The Scheduler's Perspective on the Worker}
\label{subsec:worker-perspective}

The scheduler's perspective on the worker has the following methods:

\begin{methoddesc}%
{start\_calculation(dbname, username, password, sessid, stochastic\_values)}
\begin{tabular}{|p{0.2\textwidth}|p{0.75\textwidth}|} \hline
{\bf Name} & {\tt start\_calculation} \\ \hline

Description &
	Calculate a number of shots specified by the stochastic values 
	for the given session. 
	\\ \hline

In	&
	\parameter{dbname}, \parameter{username}, \parameter{password},
	\parameter{sessid}, \parameter{stochastic\_values}
	\\ \hline

In definition &
	\parbox[t]{0.75\textwidth}{
		\begin{tabular}[t]{p{0.30\textwidth}p{0.40\textwidth}}
			\parameter{dbname}: & DB instance \\
	 		\parameter{username}: & User name \\
			\parameter{password}: & Password \\
			\parameter{sessid}:   & Session identifier \\
			\parameter{stochastic\_parameters}:   & 
				Dictionary of tuples:
		\end{tabular}

		\begin{itemize}
		    \item Dictionary: A tuple of values for 
		    	each stochastic parameter. 
		
		    \item Number of Monte-Carlo shots given by
			length of tuples.

		    \item Dictionary keys are the tuples returned by 
		    	\parameter{session\_stochastic\_parameters}.
		\end{itemize}
	  } \\ \hline

Return	&
	List of aggregated results of the calculations.
	The number and structure of return values depends on the 
	model selection
	\\ \hline
Return definitions	&
	\\ \hline
\end{tabular}
\end{methoddesc}


\begin{methoddesc}%
{stop\_calculation()}
\begin{tabular}{|p{0.2\textwidth}|p{0.75\textwidth}|} \hline
{\bf Name} & {\tt stop\_calculation} \\ \hline
Description
	& Stop the currently running calculation. \\ \hline
\end{tabular}
\end{methoddesc}

\begin{methoddesc}%
{session\_stochastic\_parameters(dbname, username, password, sessid)}
\begin{tabular}{|p{0.2\textwidth}|p{0.75\textwidth}|} \hline
{\bf Name} & {\tt session\_stochastic\_parameters} \\ \hline

Description 
	& Return a list of parameters that have to be varied throughout the
	  simulation. Whether this variation is done by random numbers or 
	  a more systematic way is up to the scheduler. \\ \hline

In	
	& \parameter{dbname}, \parameter{username}, 
	  \parameter{password}, \parameter{sessid} \\ \hline

In definitions 
	& \parbox[t]{\textwidth}{
	    \begin{tabular}[t]{p{0.18\textwidth}p{0.52\textwidth}}
		\parameter{dbname}: & DB instance \\
	 	\parameter{username}: & User name \\
		\parameter{password}: & Password \\
		\parameter{sessid}:   & Session identifier
		\end{tabular}
	  } \\ \hline

Return
	& List of Python tuples: \\
	& (\parameter{blockid}, 
	  \parameter{fieldid},
	  \parameter{distribution}, \parameter{objectid}) \\ \hline

Return definitions
	&
	\parbox[t]{0.8\textwidth}{
	    \begin{tabular}[t]{p{0.18\textwidth}p{0.52\textwidth}}
		\parameter{blockid}: & Parameter Block ID as defined in 
	  			   	PARA\_TREE\_DEF\_TAB. Together with 
					fieldid identifies a parameter. \\ 
		\parameter{fieldid}: & Parameter Field ID as defined in 
	  				PARA\_TREE\_DEF\_TAB. Together with 
					blockid identifies a parameter. \\
		\parameter{distribution}: & Indicating the distribution of the 
	  				parameter, \texttt{"uniform"}, 
					\texttt{"normal"} or
	  				\texttt{"lognormal"}. \\
		\parameter{objectid}:  & Used when a parameter has to be 
					variied independent for each object 
					it is related to. These are identified 
					by the \parameter{objectid}. If 
					the parameter is applied
	  				general the objectid is set to '-1'.
		\end{tabular}} \\
					\hline
\end{tabular}
\end{methoddesc}


\begin{methoddesc}%
{session\_required\_parameters(dbname, username, password, sessid)}
\begin{tabular}{|p{0.2\textwidth}|p{0.75\textwidth}|} \hline
{\bf Name} & {\tt session\_required\_parameters} \\ \hline
Description &
	Return the parameters required for a simulation in the given session.
	\\ \hline	

In 	&
	\parameter{dbname}, \parameter{username}, 
	\parameter{password}, \parameter{sessid}
	\\ \hline

In definitions	&
	 \parbox[t]{\textwidth}{
	    \begin{tabular}[t]{p{0.18\textwidth}p{0.52\textwidth}}
		\parameter{dbname}: & DB instance \\
	 	\parameter{username}: & User name \\
		\parameter{password}: & Password \\
		\parameter{sessid}:   & Session identifier
		\end{tabular}
	  } \\ \hline

Return	&
	List of Python tuples: (\parameter{blockid}, \parameter{fieldid})
	\\ \hline

Return definitions: &
	blockid and fieldid are used as in the PARA\_TREE\_DEF\_TAB and 
	in combination uniquely identify a parameter in the database.
	\\ \hline
\end{tabular}
\end{methoddesc}


\begin{methoddesc}%
{session\_missing\_parameters(dbname, username, password, sessid)}
\begin{tabular}{|p{0.2\textwidth}|p{0.75\textwidth}|} \hline
{\bf Name} & {\tt session\_missing\_parameters} \\ \hline

Description &
	Return the parameters required for a simulation that are not yet
	specified in the given session.
	\\ \hline	

In 	&
	\parameter{dbname}, \parameter{username}, 
	\parameter{password}, \parameter{sessid}
	\\ \hline

In definitions	&
	 \parbox[t]{\textwidth}{
	    \begin{tabular}[t]{p{0.18\textwidth}p{0.52\textwidth}}
		\parameter{dbname}: & DB instance \\
	 	\parameter{username}: & User name \\
		\parameter{password}: & Password \\
		\parameter{sessid}:   & Session identifier
		\end{tabular}
	  } \\ \hline

Return	&
	List of Python tuples: (\parameter{blockid}, \parameter{fieldid})
	\\ \hline

Return definitions: &
	blockid and fieldid are used as in the PARA\_TREE\_DEF\_TAB and 
	in combination uniquely identify a parameter in the database.
	\\ \hline
\end{tabular}
\end{methoddesc}


