\setlength{\itemsep}{4cm}
\chapter{Concept}
\label{chap:concept}

\section{General Overview}
\label{sec:generaloverview}

\begin{center}
\FigNoEntry{\includegraphics[width=\textwidth]{./great-er_model_components.eps}}{
\label{fig:ComponentOverview}GREAT-ER Model Suite Component Overview}
\end{center}

Figure 1.\ref{fig:ComponentOverview} gives an overview of the GREAT-ER 2
architecture and the components covered by this specification.
Components with direct relation to GREAT-ER Model Suite are displayed in
grey, others in white.

The core component is the GREAT-ER Model Suite, which 
\begin{itemize}
	\item provides required parameter lists
	\item checks current parameter settings for completeness
	\item performs simulation runs
\end{itemize}

Figure 1.\ref{fig:ComponentDetails} illustrates the component details of
the GREAT-ER Model Suite. 

\section{Scheduler - Worker Concept}

\begin{center}
\FigNoEntry{
    \includegraphics[width=\textwidth]{./great-er_model_component_details.eps}}{
        \label{fig:ComponentDetails}GREAT-ER Model Suite Component Details
    }
\end{center}

The model suite consists of a scheduler process (chapter \ref{chap:scheduler})
which communicates with the user interface and the webserver and 
delegates the actual simulation to separate 
worker processes (chapter \ref{chap:worker}).
Only the scheduler communicates with the worker processes.

The worker processes and the scheduler communicate via the network and
may run on separate machines. This architecture allows the simulation to
be distributed over several workers at once to speed up the simulation run
and concentrates the knowledge about the models in the workers. The
workers may of course also run on the same system as the scheduler which
in turn could run on the same machine as the client.

The clients --- the
web-server and the user interface --- connect to the server to start and
stop simulations, to query the current status of a simulation or to
retrieve information about the supported models.
The scheduler can manage multiple concurrent simulations for different
users and from different clients.

A worker works for only one scheduler process. It can handle concurrent 
simulations by performing a complete Monte-Carlo shot per simulation 
managed in a round robin fashion.

\subsection{Simulation Run Flow}

A simulation run generally consist of the following steps:

\begin{enumerate}

  \item \label{sched:sim_start} The client calls the scheduler to start
  a simulation

  \item \label{sched:sim_delegate} The scheduler delegates the
  simulation to one or more worker processes.
  The worker processes may run on separate machines or on the same one.

  This step includes generation of (pseudo) random numbers for use in
  the Monte-Carlo shots in the workers. The random numbers are computed
  in the scheduler to make sure that there's no accidental correlation
  due to two workers using the same seeds and algorithms in the random
  number generators. It also allows the use of more systematic
  approaches in the future like Latin-Hypercube and Hammersley whose
  implementation needs central coordination.

  \item \label{sched:partial_result} When a worker is finished with
  their part of a simulation they transfer the aggregated results back
  to the scheduler.

  \item \label{sched:aggregate} When all workers taking part in a
  simulation have completed their work the scheduler aggregates the
  results of the individual workers into the final simulation result.

  \item \label{sched:write_results} The simulation result is written
  into the database.

  \item \label{sched:sim_done} The client determines that the simulation
  is completed. The client has to actively poll for the state of the
  simulation so it can't be informed when the simulation has been
  finished (see section \ref{sec:client-scheduler-xmlrpc} for more
  information)

\end{enumerate}

\subsection{Database Access}
\label{sec:sched-database}

Both the scheduler and the workers need access to the database.
Therefore the clients pass the userid and password to use for database
access to the scheduler when starting a simulation. All database access
for a given simulation run is done with these settings through the
DB-API implementation.


\section{Software}
\label{sec:software}

All software tools the GREAT-ER Model Suite are chosen under the
conditions of being Free Software and providing platform independence.

The scheduler and worker are implemented in Python using the 
Twisted framework for network applications. 
Twisted is built around non-blocking sockets so
that a program implemented with Twisted can be run in a single thread
that is implemented in an event-oriented way.

\section{System segmentation}
\label{sec:system_segmentation}

The term system in this section means an environmental system under
investigation.

The backbone of the system structure of GREAT-ER 1.0 is the river network.
The network is splitted into stretches of different types: spring, confluence,
bifurcation and discharge. Based on these elements the river network can be
seen as a directed graph, where the first three stretch types have mainly 
topological meaning. The latter element is more special because an additional
chain of models is embedded: Emission, sewer and WWTP. However, the graph
structure is limited to the river network. 
Figure \thechapter.\ref{fig:structure_great-er_1}
illustrates the situation.

\begin{center}
\FigNoEntry{
    \includegraphics[width=0.95\textwidth]{./structure_great-er_1.eps}}{
        \label{fig:structure_great-er_1} System structure GREAT-ER 1.0
    }
\end{center}

The approach for GREAT-ER 2.0 extends the segment concept to all models. The
directed graph is not limited to the river network with a static chain of
models linked to a discharge point as described above. The different models are
represented by specific segments and therewith part of the directed graph
(Figure \thechapter.\ref{fig:structure_great-er_2}).
This approach provides higher flexibility in extending and combining the model
collection. 

\begin{center}
\FigNoEntry{
    \includegraphics[width=0.95\textwidth]{./structure_great-er_2.eps}}{
        \label{fig:structure_great-er_2} New system structure for GREAT-ER 2.0
    }
\end{center}
\clearpage

\section{Parameter Information}
\label{sec:parameter_information}

\subsection{Parameter Requirement Information}
\label{subsec:PRI}

\subsubsection{Rationale}
\label{subsubsec:PRIrationale}

The user interface supports the user with filling parameters
for a simulation. One aspect of this is an indicator on which
parameters actually must be specified to run a simulation with
the current model selection (i.e. if volatilization is
switched on, certain parameters are required for the model equations -
if volatilization is switched off, the user should clearly see that
she has not to fill in the corresponding fields).

\subsubsection{Component Communication Path}
\label{subsubsec:PRIComponentCommunicationPath}

\begin{enumerate}
\item	A model parameter Dialog is closed with OK.
\item	The changes are committed to the database (i.e. to the
		temporary session).
\item	The UI component requests a list of the required parameters
		from the Model Scheduler for the given session.
\item	The Model Scheduler hands over the request to a Worker instance.
\item	The Worker instance loads the parameter selection from the database
		and tests which parameters are required, compiles a list
		of (field\_id, block\_id) tuples and returns this list to the
		Model Scheduler.
\item	The Model Scheduler returns the list to the UI component.
\item	The UI component uses the list to set the required-indicators
		for the parameters. The next dialog that is opened uses
		this information and enables/diables the symbol for necessary
		parameters accordingly.
\end{enumerate}

\subsection{Parameter Distribution Information}
\label{subsec:PDI}

\subsubsection{Rationale}
\label{subsubsec:PDIrationale}

The GREAT-ER Model system provides a Monte-Carlo based simulation approach
where some parameters are always distributed and others always fixed. A
significant amount of parameters distribution can be determined by the user.

While the Scheduler communicates with the User Interface and has to control 
the simulation progress, the information about models and their requirements is
implemented at the Worker side.

\subsubsection{Component Communication Path}
\label{subsubsec:PDIComponentCommunicationPath}

\begin{enumerate}
\item	Selecting the "Simulation/Start" item the client writes the 
		session data to the database and calls the Scheduler 
		to run a simulation.
\item 	The Model Scheduler requests a Worker instance for a list 
		of parameters to be considered as distributed for the 
		given session.
\item 	The Worker loads the session settings from the database and based on
		the model selection and parameter settings compiles a list
		of (field\_id, block\_id, distribution type) 
		tuples and returns this list to the Model Scheduler.
\item 	The Scheduler generates a batch of lists of 
		(field\_id, block\_id, 
		value from standard distribution\footnote{
			Standard distribution in this case means e.g. 
			a standard normal distribution or a [0,1]-uniform 
			distribution, etc.}) 
		tuples representing single Monte-Carlo shots.
\item 	The batch of shots is splitted to the registered Worker instances.
\item 	For a given shot a Worker derives based on the descriptive 
		distribution parameters the specific values 
		for a segment. 
\end{enumerate}

\subsection{Information Storage}

The information about required parameters is provided by the models, which are
implemented as classes. The base class Model provides methods to analyse
the model requirements and the user settings. The requirements have to be
implemented by a model developer as a nested list:

\begin{enumerate}
\item	The first tuple of a list names a parameter pointing out if the
		current user settings imply requirement of the lists contents:
		(field\_id, block\_id, 
		value to set the parameter\footnote{This is needed since 
		parameters like RIVER\_MODEL can flag different states and are
		not simply boolean.}
		).
\item 	All further items of the list are either (field\_id, block\_id) tuples
		describing parameters or lists.
\end{enumerate}
