\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.

A single worker may be running (parts of) several simulations
simultaneously. These parts must belong to different simulations.

\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, simid, 
		    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{simid}, \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{simid}:    & Simulation id \\
			\parameter{stochastic\_parameters}:   & 
				Dictionary of tuples or None:
		\end{tabular}
		\vspace{-1.5\topsep}
		\begin{itemize}
		    \item Dictionary: A tuple of values for 
		    	each stochastic parameter. 
		\vspace{-1.5\parskip}
		    \item Number of Monte-Carlo shots given by
			length of tuples.
		\vspace{-1.5\parskip}
		    \item Dictionary keys are the tuples returned by 
		    	\parameter{session\_stochastic\_parameters}.
		\vspace{-1.5\parskip}
		    \item If \parameter{stochastic\_parameters} is None a 
		    	single deterministic shot is calculated.
		\end{itemize}

		It is an error if the worker is already working on a
	        calculation with the same simid.
	} \\ \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(simid)}
\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}

\section{Configuration}

The worker provides various options to configure the model system 
for an installation:

\begin{tabular}{|p{0.2\textwidth}|p{0.75\textwidth}|} \hline
{\bf Option} & {\tt Description} \\ \hline
Port & The port a running scheduler listens for connections.\\ \hline
Host & The host the scheduler is running on. By default this is localhost;
       with this option a larger computing can be set up distributing a 
       simulation for large catchments or a high number of Monte-Carlo shots 
       over several computers. \\ \hline
Admin Port & The port to listen on for administrative XMLRPC calls. 
             The worker can be shut down via XMLRPC calls on this port if
             the calls originate from localhost. 
             
             This feature is especially for
             the server usages of the GREAT-ER model systems since common users
             typically do not have accounts on dedicated servers.\\ \hline
Info File & If specified process name and admin port are stored in the
            file for later use (e.g. in a stop script, see below).

            This feature is especially for the server uses of the 
            GREAT-ER model systems.
\\ \hline
Log File & If specified the worker writes extensive logs into the file for
            activity monitoring and problem analysis.\\ \hline
Test Port & This feature is especially for the unit testing during 
            development and can be used for special test commands. \\ \hline
DB API Module & This feature is especially for the unit testing during 
            development and can be used to specify dummy test databases.
 \\ \hline
\end{tabular}

\subsection{Starting the Worker}

The Worker can be started using the \verb+start_worker.py+
start script. The script provides several command line options to 
configure the worker:

{\scriptsize
\begin{verbatim}
  -p, --port=           The port the scheduler listens on for workers [default: 10102]
  -h, --host=           The host the scheduler is running on [default: localhost]
      --admin-port=     port to listen on for admin commands
      --info-file=      file to write info about the worker process to (pid and
                        admin port).
      --test-port=      Port number to listen on for special commands from the
                        test-suite
      --log-file=       name of file to log to
      --db-api-module=  Name of the db interface implementation module 
      			[default: _dagreater]
      --help            Display this help and exit.
\end{verbatim}
}

\subsection{Stopping the Worker}

The worker can be stopped using the \verb+stop.py+
script. The script reads the information from a specified info file 
and stops the corresponding worker.

\begin{verbatim}
Usage: python stop.py [info-file]
\end{verbatim}

The GREAT-ER Desktop Client stops a locally started worker automatically on
exit.


