%vim:set tw=68:
% $Source: /home/bricks/source/greater/cvs/greaterrepository/GREAT-ERWeb/doc/great-er_web_manual.tex,v $
% $Id: great-er_web_manual.tex,v 1.9 2003-07-28 12:30:37 frank Exp $
\documentclass[a4paper,twoside,BCOR19mm]{scrbook}
\usepackage[latin1]{inputenc}
\usepackage{graphicx}
\usepackage{times}
\usepackage{fancyhdr}
\usepackage{lastpage}

\def\cleanunderscore#1_#2_#3{\expandafter #1\_#2\_#3}
\def\CVS$#1: #2 ${\expandafter\def\csname CVS#1\endcsname{\cleanunderscore#2}}
\CVS$Id: great-er_web_manual.tex,v 1.9 2003-07-28 12:30:37 frank Exp $

%----------------------------------------------
% Document DATE and VERSION
% set these values when releasing a new version

\newcommand{\documentdate}{23 July 2003}
\newcommand{\documentversion}{1.0.0}
\newcommand{\documentID}{\CVSId}

%----------------------------------------------

% Makros:
%       \Fig{figure}{text}      : creates an mbox around 'figure' and
%                                 writes 'text' at the bottom with leading
%                                 'Fig. section.figno:'.
%                                 Example:
%                                 \Fig{\epsfxsize30mm \epsffile{x.eps}}{the x}\\%       \FigNoEntry{}{}         : same as above, no entry in figures list
%
%       \FigNoCaption{}         : same as above, having no caption
%
%       \FigCaption{}           : line with figure caption, setting figure
%                                 counter and figures list

%****************************************************************************
%       Figure makro for graphics continously enumerated.
%

\newcounter{FigCnt}[chapter]
\newcommand{\Fig}[3]%
{
        \refstepcounter{FigCnt}
        \addcontentsline{lof}{figure}%
                {\protect\numberline{\thechapter.\arabic{FigCnt}}{#2}}
        \mbox{#1}
\nopagebreak

        {Fig. \thechapter.\arabic{FigCnt}: #3}
}

\newcommand{\FigNoEntry}[2]%
{
        \refstepcounter{FigCnt}
        \mbox{#1}
\nopagebreak

        {Fig. \thechapter.\arabic{FigCnt}: #2}
}

\newcommand{\FigCaption}[1]%
{
        \refstepcounter{FigCnt}
        \addcontentsline{lof}{figure}%
                {\protect\numberline{\thechapter.\arabic{FigCnt}}{#1}}

        %{Figure \thechapter.\arabic{FigCnt}: #1}
}

\newcommand{\FigNoCaption}[1]%
{
        \mbox{#1}
\nopagebreak

}

\newcommand{\imagescale}{1.0}

\begin{document}

%-----------------------------------
% define header/footer
% The settings here are for single page documents (only odd page set)

% for some pages latex switches back to pagestyle plain :-(
\fancypagestyle{plain}{%
	\fancyhf{} % clear all header and footer fields
	\fancyhead[LO,RE]{\footnotesize GREAT-ERWeb Manual\\ \leftmark}
	\fancyfoot[RO,LE]{\footnotesize Intevation GmbH} % Author
	\fancyfoot[CO,CE]{\footnotesize \thepage/\pageref{LastPage}}
	% set the document title for the footer here!
	\fancyfoot[LO,RE]{\footnotesize \documentdate \\\documentID}
	\renewcommand{\footrulewidth}{0.4pt}
}

% and now define pagestyle fancy
\fancyhead{} % clear all fields
\fancyhead[LO,RE]{\footnotesize GREAT-ERWeb Manual\\ \leftmark}

\fancyfoot{}% clear all fields
\fancyfoot[RO,LE]{\footnotesize Intevation GmbH} % Author
\fancyfoot[CO,CE]{\footnotesize \thepage/\pageref{LastPage}}
% set the document title for the footer here!
\fancyfoot[LO,RE]{\footnotesize \documentdate \\\documentID}

\renewcommand{\footrulewidth}{0.4pt}

\pagestyle{fancy}

%-----------------------------------

\parindent0cm

%-----------------------------------
% TITLE PAGE
{
	\includegraphics[width=0.3\textwidth]{./brieflogo.eps}\\[0.1cm]

	 {\tt http://intevation.net}\\[2.0cm] 
}

% reenter the TITLE here
{
	\sffamily\bfseries\Large 
% e.g.:
	GREAT-ER II\\[0.5cm]
	\huge GREAT-ER Web Manual\\[4cm]

}

% a possible SUBTITLE
%\begin{flushleft}
%	\sffamily\bfseries\large 
%    	by Intevation GmbH\\[0.5cm]
%\end{flushleft}

\thispagestyle{empty}

\vfill

{\sffamily\small
	Intevation GmbH\\
	Georgstrasse 4\\
	D-49074 Osnabrück\\
	Germany\\
	\\
	Date: \documentdate
}


\newpage

\vfill

This document has been designed with \LaTeX{}.
It is available as source code, PDF- and HTML-format.\\

Version: \documentversion \\
Date: \documentdate \\
Author: Silke Reimer

\vfill

\begin{center}Copyright (c) 2003 Intevation GmbH.\end{center}

    Permission is granted to copy, distribute and/or modify this document
    under the terms of the GNU Free Documentation License, Version 1.2
    or any later version published by the Free Software Foundation;
    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
    A copy of the license is included in the section entitled ``GNU
    Free Documentation License''.

\tableofcontents

\chapter{User Interface}

\section{Main Window}

The main window is the core of the GREAT-ER Web Interface, it consists of
three frames for Menu with Status Box, Dialog Box and Map each. If a
catchment has been opened a Tool Bar appears within the map.

\begin{center}
\Fig{\includegraphics[width=0.95\textwidth]{screenshots/elements.eps}}{
     GREAT-ER Web Elements}{GREAT-ER Web Elements}
\end{center}


\subsection{Menu}

The menu frame provides access to the various actions needed to perform a
simulation (i.e. session management, substance editing, catchment selection,
etc.). Depending on the current status of a simulation session menu items 
are enabled or disabled (grayed out).

\subsection{Status Box}

The status bar provides information on the status of the 
database connection: If connected the username used for the authentication
is displayed. Additionally some information about the current session is
shown: If a session is open its name, catchment name and substance name is
displayed. Also it is indicated if there are results available for the
current session.

\subsection{Dialog Box}

In the Dialog Box dialogs are displayed, offering various functionality like
session selection, parameter editing or general information. These dialogs are
discussed in detail below.
 
\subsection{Map}

If already specified the map displays the catchment area: river network,
discharge points and catchment boundary. 

\subsection{Tool Bar}

The tool bar covers first some self-explaining buttons to navigate on the
geographic data displayed on the map. The last three buttons provide tools to
edit the market data and discharge data by selecting discharge points on the
map and to get a concentration profile by selecting a stretch. The latter
is only possible if some results are available.


\pagebreak

\section{Menu Session}

\subsection{New Session}

The menu item is enabled once a database connection is established.
A dialog similar as for Edit Session (see section \ref{editsession}) is raised
to enter the session's name, substance, catchment and comment.
All but the name is optional and can also be specified later.

If a session is open with unsaved modifications the user
is offered a dialog to save the session before creating a new one.

\subsection{Open Session \label{opensession}}

This menu item is enabled if a database connection has been
established (via Authenticate). The dialog that appears
is separated into two areas: on the left a list is presented
containing all available sessions, public and personal ones.

In the right area, additional information on the currently selected
scenario can be displayed on command: substance and catchment name as well
as the session comment. Furthermore, the access rights are shown with the
owner of the session, his group and the privileges for the session.
Sessions without the privileges for you to at least view it are not listed.

To load a session the OK button.

\begin{center}
\Fig{\includegraphics[width=\textwidth]{screenshots/opensession-dlg.eps}}{
     Open Session Dialog}{Open Session Dialog}
\end{center}

If the previously loaded session was modified but not saved and if the
user is privileged, a dialog is raised to allow saving of the
previous session.

\subsection{Edit Session \label{editsession}}

If there is a current session, this menu item is enabled.
A dialog is raised to modify the session's name, substance,
catchment, comment and privileges.

\begin{center}
\Fig{\includegraphics[scale=\imagescale]{screenshots/editsession-dlg.eps}}{
     Edit Session Dialog}{Edit Session Dialog}
\end{center}

The changes are not stored in the database unless a
Save Session operation is performed. This is only possible for the
privileged user.

The substance and catchment can alternatively be changed
in the corresponding menus. The open substance dialogs shows more
details on the actual substance during the selection.

\subsection{Save Session}

This item is only available for the privileged user.
It is enabled if there is an open session which
has been modified. All session data in the database
will be overwritten with the current session without further request.

{\bf Note,} that when saving a session, your ID will be applied
overwriting the user ID of the previous owner.

Saving a session may fail for two reasons:

\begin{enumerate}
\item	You don't have the permission to write.\newline
		This happens if you opened a session where you have only
		privileges to view. In this case, use 'Save Session As' 
		to create your own copy.
\item	Another user opened the same session and saved it meanwhile.
		In this case, use 'Save Session As' to create your own copy.
\end{enumerate}

\subsection{Save Session As}

If a session has been opened this menu item is enabled and
allows to store the current session separate from the
original session.

{\bf Note}, that the new session will be the one which will be 
loaded in the client after a 'Save Session As'.

A dialog  is raised allowing to change name and comment of the session so
that it can be distinguished from the original one.

{\bf Note,} that the session's name
does not need to be unique in the database and hence multiple
sessions with the same name may exist.
You should avoid this situation by specifying different names.

\subsection{Close Session}

This menu item is always active if there is an open session.

If the current session is modified and if the user is privileged, the user
is offered the option to save the changes before actually closing the
session.

\subsection{Delete Session}

This option is always available to a privileged user with an established
database connection.

A dialog similar as for Open Session (see section \ref{opensession})
is opened allowing to select
the session that should be removed from the database.

After selection, the user is required to confirm the action.

\section{Menu Substance}

The Substance Menu provides access to the substance data.  The menu items
'New Substance' and 'Open Substance' are enabled if a
session has been opened or newly started. For the privileged user also
'Delete Substance' is enabled in this case. The 'Edit Substance' 
item is only enabled if the session already contains substance
data. If the user is privileged, 'Save Substance' is then enabled, too.

\subsection{New Substance}

A Dialog similar as for Edit Substance (see section \ref{editsubstance}) is
raised to enter the substance name, comment and its various parameter.  All
but the name is optional and can also be specified later.

If the open session already contains substance data a warning 
dialog will be raised.

{\bf Note}, that adding a new substance implies to delete all 
market, discharge and result data from the current session since they 
potentially don't have a valid link to the session data with 
the new substance data.

\subsection{Open Substance\label{opensubstance}}

The dialog that appears is separated into two areas:
on the left a list is presented
containing all available substances.

In the right area, the comment on the highlighted
substance can be displayed on command together with owner and privileges.

To load a substance hit the OK button.

\begin{center}
\Fig{\includegraphics[scale=\imagescale]{screenshots/opensubstance-dlg.eps}}{
     Open Substance Dialog}{Open Substance Dialog}
\end{center}

{\bf Note}, that opening another substance data set implies to delete all
market, discharge and result data from the current session since they
potentially don't have a valid link to the session data with the new
substance data.

\subsection{Edit Substance\label{editsubstance}}

This action is only available if a substance has been selected.
A dialog is opened for entering all properties of the
substance. 

\begin{center}
\Fig{\includegraphics[scale=\imagescale]{screenshots/editsubstance-dlg.eps}}{
     Edit Substance Dialog
}{Edit Substance Dialog}
\end{center}

If a parameter is distributed you can recognize it by the added
name of the distribution at the end of the value (p.e. '0.3/none' or
'0.3;0.82/uniform'). You
have the following possibilities to enter new values for a distributed
parameter:
\begin{itemize}
\item Enter a decimal or integer: The parameter will get the distribution
type 'none', i.e. not distributed.
\item Enter a decimal or integer + '/none': The parameter will get the distribution
type 'none', i.e. not distributed.
\item Enter two decimals or integer, separated by a semicolon: The parameter
will be distributed with distribution type 'uniform' which is the default
distribution.
\item Enter two decimals or integer, separated by a semicolon +
\verb+<dist_type>+: \verb+<dist_type>+ has to be one of 'normal', 'lognormal' or
'uniform'. The parameter will then be distributed
with the specified distribution type.
\end{itemize}

If an incorrect value has been inserted, a dialog will be raised to inform
you about the wrong parameter.

% The substance data are separated into various sections.
% {\bf Note,} that the structure and contents is defined in the database
% and may have been changed by the database administrator):

\paragraph{Identification}

The substance name, CAS and EINECS number and additional synonyms
can be specified to aid identification. The substance name is obligatory,
all other parameters are optional.

\paragraph{WWTP Removal}

Depending on the type of the waste water treatment plant (WWTP) different
removals have to be applied. They can be specified in this section.

\paragraph{River Removal}

You can change the instream-removal elimination rate assumed for every
stretch in the river network.

\paragraph{Emission Data}

You can specify a default domestic consumption (kg per capita and year)
of the substance assumed for any discharge site in the simulation area.

\subsection{Save Substance}

This item is only available for the privileged user. 
The Save Substance Substance Dialog is raised allowing to specify the name
and comment for the new substance entry.

\begin{center}
\Fig{\includegraphics[scale=\imagescale]{screenshots/savesubstance-dlg.eps}}{
     Save Substance Dialog
}{Save Substance Dialog}
\end{center}

\subsection{Delete}

This item is only available for the privileged user.  A dialog similar to
the Open Substance Dialog (see section \ref{opensubstance}) is raised
allowing to select a substance from the database to be removed.

\section{Menu Catchment}

\subsection{Open Catchment}

This menu item is enabled if a database
connection has been established and a session been opened
or newly started.

A dialog is raised where you can select a new catchment for the active
session from the list of catchments in the database.

{\bf Note,} that with a the new catchment selection current 
simulation results, market data and discharge data entries will be deleted.

\begin{center}
\Fig{\includegraphics[scale=\imagescale]{screenshots/opencatchment-dlg.eps}}{
     Open Catchment Dialog}{Open Catchment Dialog}
\end{center}

\section{Menu Model}

This menu provides items for simulation control.

\subsection{Edit Model Params}

This item is only enabled if there is an active session.
It allows you to specify the number of Monte-Carlo shots of a
simulation.  A Monte-Carlo-Shot number of 0 is equal to a conventional,
non-stochastic simulation where for all distributed
parameters the mean values are applied.

%Background concentrations are included to consider additional
%loads within the river network which might be monitored
%upstream from the first known discharge.
%Note that the given value is simply added to the model results
%after simulation.
%The background concentration is not considered within the
%elimination processes.

%The concentration has to be entered before running a simulation.
%The unit is always mg/L.
%After the simulation  the specified  background concentration
%will be added to the model results.
%If the model results are displayed in a different unit an
%automatic conversion will be activated for the background concentration.

Please {\bf note} that GREAT-ER Web only allows for running a simulation in
model mode 1. Editing the Monte-Carlo shots therefore also changes the model
modes entries for the current session.

\subsection{Run Simulation}

This item is only available if there is an active session with catchment
and substance.  This command will start the simulation for the active
session if all required data have been specified. If the parameters are not
sufficiently specified, a dialog is raised to inform you about the 
missing parameters. 

{\bf Note}: The application won't inform you about a finished simulation of
it's own. You have to use the menu item 'check status' to get this
information.

\subsection{Stop Simulation}

This item is only available if a simulation has been started.  It will stop
a running simulation. A dialog appears to inform you about the successfully
stopped simulation.

\subsection{Check Status}

This item is only available if a simulation has been started.  It informs
you about the current state of the simulation. If the simulation has been
finished, the Map will be refreshed showing the new calculated results. 

\section{Analysis}

\subsection*{PEC Initial}

The spatial aggregation of concentrations in the river
directly after emission.

\begin{center}
\Fig{\includegraphics[scale=\imagescale]{screenshots/pecinitial-dlg.eps}}{
     PEC initial}{
	 PEC initial}
\\
\end{center}

This is similar to the PEC local ad defined in the EU Technical
Guidance Documents (EU, 1996), although its calculation is different.
Based on the $C_{sim,start}$ mean values, the mean is calculated
for all stretches receiving treated or untreated discharges.

Compare Boeije et al., 1999.

\subsection*{PEC Catchment}
This is the average of representative concentrations over the entire
catchment. 

\begin{center}
\Fig{\includegraphics[scale=\imagescale]{screenshots/peccatchment-dlg.eps}}{
     PEC catchment}{
	 PEC catchment}
\\
\end{center}


This is a new concept for geo-referenced exposure assessment,
although there is some analogy with the PEC regional in the EU Technical
Guidance Documents (EU, 1996).

\section{Login}

This menu item is available if you are logged in as normal, non privileged
user. 
A dialog for setting up connection to a GREAT-ER database
allows to enter database, username and password for the
authentication process. 

\begin{center}
\Fig{\includegraphics[scale=\imagescale]{screenshots/authenticate-dlg.eps}}{
     Authentication Dialog}{Authentication Dialog}
\end{center}

Successful authentication will activate display of
menu items only available for privileged users, namely 'Save Session', 'Save
Session As', 'Delete Session', 'Save Substance' and 'Delete Substance'.
Apart from 'Delete Session' they are all disabled and will only become
available after opening or creating a new session.

Also, the Login menu item disappears and a 'Logout' menu item is
displayed. 

The database connection can be closed via the menu item
Logout. Leaving the GREAT-ER Web application by simply closing the Browser
leads to unaccessible session in the database. They will be removed after two
days when the user is logging in again. 

\section{Logout}

Once a database connection has been established, this menu
item is active. It will close the current session and then
disconnect from the database.
If the session is modified, the user is offered an option to save the 
modifications before closing the session.


\section{Map Frame}

If no catchment has been selected, the map frame is empty. Otherwise It
consists of three parts. 

On the left side a map with catchment boundary,
rivernet work and  discharge sites is displayed. On the top left corner you
find a tool bar that provides facilities for navigation on the map and
additional functions (see section \ref{toolbar}). 

On the right side a legend and a reference map is displayed. The legend
enables to switch on or off specific layers of the map. Please reload the
map after checking a new box (see subsection \ref{navigation}).

The reference map
gives an orientation where the actual extent of the main map is located.
Furthermore you can use the reference map to recenter the main map by
clicking on the corresponding location.

\begin{center}
\Fig{\includegraphics[angle=90,scale=0.80]{screenshots/map.eps}}{
     Map Frame}{Map Frame}
\end{center}


\section{Tool Bar}
\label{toolbar}

\subsection{Navigation}
\label{navigation}

\paragraph{Zoom In}
\FigNoCaption{\includegraphics[width=0.6cm]{icons/icon_zoomin.eps}}
This button activates the Zoom-in tool. You may now draw a rectangle which
will define the extent of the new area to be displayed. If the shape of
the rectangle and the map is different the zoom factor is automatically
changed to cover the whole selected area. You can also click once anywhere
in the map to zoom in with a fixed factor.

\paragraph{Zoom Out}
\FigNoCaption{\includegraphics[width=0.6cm]{icons/icon_zoomout.eps}}
This button activates the Zoom-out tool. Clicking it leads in zooming out
with a fixed factor.

\paragraph{Recenter}
\FigNoCaption{\includegraphics[width=0.6cm]{icons/icon_recentre.eps}}
This button activates the Recenter tool. You can now click on some point on
the map. The map will be reloaded with this point as its new center.

\paragraph{Reload}
\FigNoCaption{\includegraphics[width=0.6cm]{icons/icon_reload.eps}}
After clicking this button the map will be reloaded. This is useful if you
have checked in or out a new layer in the legend.\\

\paragraph{Full Extent}
\FigNoCaption{\includegraphics[width=0.6cm]{icons/icon_fullextent.eps}}
This button reloads the map with full extent.

\subsection{Edit Emission Data}

\FigNoCaption{\includegraphics[width=0.6cm]{icons/icon_emission.eps}}
This button activates the Edit Emission Data tool.
You can now select a discharge site with the mouse pointer
to change its specific consumption and release attributes.

The Edit Emission Data dialog enables you to specify site-specific
consumption data.  To cover industrial sites, users can enter an additional
input into the treatment plant. This input reflects discharges resulting
from the production processes and can be calculated from the production
volume.

\begin{center}
\Fig{\includegraphics[scale=\imagescale]{screenshots/editmarketdata-dlg.eps}}{
     Edit Emission Data Dialog}{Edit Emission Data Dialog}
\end{center}

Please note that in case of an unknown specific value the general 
value will be applied for a simulation\footnote{E.g. for an unknown 
consumption the simulation falls back to the consumption specified under
the Substance Data Dialog}.

Please note that the calculation of the fraction of the production
volume which will be released is not part of GREAT-ER but must
be calculated manually beforehand.
The input considered here is the mass flow of substance into the
treatment plant in kg/a.
As with the loads from domestic inputs, the industrial input
is subsequently processed by the treatment plant model, if present,
for the selected location.

Leaving the dialog, the Edit Emission Data tool remains active.
Selecting another tool will deactivate it.

\subsection{Edit Discharge Data}

\FigNoCaption{\includegraphics[width=0.6cm]{icons/icon_discharge.eps}}
This button activates the Edit Discharge Data tool.
You can now select a discharge site with the mouse pointer
to change its specific properties.

Similar to the Edit Emission Data dialog, the Edit Discharge Data dialog
enables users to modify the parameters of a specific treatment plant.

Several site-specific parameters can be changed.
These include population, the elimination rate (used for complexity
modes), the treated fraction of incoming sewage water (e.g. bypass
or overflow) and in general the type of treatment plant.
Incoming water from separate sources is also considered such as
domestic input, non-domestic use (this covers mainly industrial
inputs) and runoff.
If only an overall value is available for treatment plants this
should be entered as domestic flow.

\begin{center}
\Fig{\includegraphics[scale=\imagescale]{screenshots/editdischargedata-dlg.eps}}{
     Edit Discharge Data Dialog}{Edit Discharge Data Dialog}
\end{center}

Please note that domestic flow is given in liter/(capita*day), where
non-domestic flow and run-off are considered as $m^3/s$.

Please note that in case of an unknown specific values the general 
values will be applied for a simulation\footnote{E.g. for an unknown 
WWTP removal the simulation falls back to the WWTPremoval specified under
the Substance Data Dialog}.

Please note furthermore that it is possible to specify a distribution for a
general removal efficiency, but not for a site-specific removal efficiency.
Nevertheless, it is possible to have a distributed general
removal efficiency for e.g. activated sludge plants, and a fixed
rate for a selected site.

Leaving the dialog, the Edit Discharge Data tool remains active.
Selecting another tool will deactivate it.

\subsection*{Concentration Profile}

\FigNoCaption{\includegraphics[width=0.6cm]{icons/icon_profile.eps}}
After selecting the profile you have to select a stretch by clicking on the
map. Moving downstream the $C_{sim,start}$ values are collected for each
stretch. The collection will be displayed in a simply X/Y-profile.



%-------------------------Appendix-------------------------------------

\begin{appendix}

\include{gnufdl}

\chapter*{References}
\addcontentsline{toc}{chapter}{References}

\begin{description}

\item
    Boeije, G., Wagner, J.O., Koormann, F., Vanrolleghem, P.A.,
    Schowanek, D.R., Feijtel, T.C.J. (2000).
    New PEC definitions for river basins applicable to
    GIS-based environmental exposure assessment.
    Chemosphere 40(2000), 255-265.

\item EU (1996).
    Technical Guidance Documents in Support of The Commission
    Directive 93/67/EEC on Risk Assessment For New Notified
    Substances and the Commission Regulation (EC) 1488/94 on
    Risk Assessment For Existing Substances. ECB, Ispra, Italy.

\end{description}

\end{appendix}

\end{document}


