% $Id: greater-dss-model-specification.tex,v 1.18 2005-02-25 09:57:28 silke Exp $
% $Revision: 1.18 $

\documentclass[german,a4paper,oneside]{scrbook}

%----------------------------------------------
% PACKAGE MANAGEMENT
%
\usepackage[latin1]{inputenc} 
\usepackage{times}
\usepackage{fancyhdr}
%\usepackage[all, light]{draftcopy}
\usepackage{supertabular}
%\usepackage{colortbl}
%\usepackage{epsf}
\usepackage{graphicx}
\usepackage{wasysym}

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

\newcommand{\documentdate}{$Date: 2005-02-25 09:57:28 $}
\newcommand{\documentversion}{$Version$}

%----------------------------------------------
% MACRO DEFINITION
%
%   \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
%
%   \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{\APIMethod}[1]{{\small\tt #1 }}

%
% END MACRO DEFINITION
%----------------------------------------------


%----------------------------------------------
% DOCUMENT
\begin{document}


%-----------------------------------
% HEADER/FOOTER DEFINITION
% 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]{\footnotesize GREAT-ER DSS Model Specification\\ \leftmark}
	\fancyfoot[RO]{\footnotesize Intevation GmbH} % Author
	\fancyfoot[CO]{\footnotesize \thepage/\pageref{theverylastpage}}
	% set the document title for the footer here!
	\fancyfoot[LO]{\footnotesize \documentdate 
	\\great-er\_dss\_model\_specification.tex}
	\renewcommand{\footrulewidth}{0.4pt}
}

% and now define pagestyle fancy
\fancyhead{} % clear all fields
\fancyhead[LO]{\footnotesize GREAT-ER DSS Model Specification\\ \leftmark}

\fancyfoot{}% clear all fields
\fancyfoot[RO]{\footnotesize Intevation GmbH} % Author
\fancyfoot[CO]{\footnotesize \thepage/\pageref{theverylastpage}}
% set the document title for the footer here!
\fancyfoot[LO]{\footnotesize \documentdate 
\\great-er\_dss\_model\_specification.tex}

\renewcommand{\footrulewidth}{0.4pt}

%
% END Header/Footer Definition
%-----------------------------------

%-----------------------------------
% DOCUMENT SETTINGS
\pagestyle{fancy}
\parindent0cm
% \parskip0.2cm 


%-----------------------------------
% TITLE PAGE
{

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

% reenter the TITLE here
{
	\sffamily\bfseries\Large 
% e.g.:
	GREAT-ER 2.0\\[0.5cm]
	\huge Specification GREAT-ER DSS\\[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\\
	49074 Osnabrück\\
	Germany\\
	\\
	Date: \documentdate
}


\newpage

% PAGE 4

\vfill

This document has been designed with \LaTeX{}.

{\scriptsize
\begin{verbatim}
\end{verbatim}
}
%Version: \documentversion \\
%Date: \documentdate

\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.1
%or any later version published by the Free Software Foundation.
%A copy of the license is included in the section entitled "GNU
%Free Documentation License".

\tableofcontents

\chapter{Konzept}
\label{chap:concept}

Das Modellsystem aus GREAT-ER II arbeitet mit in Verbindung mit einer 
Datenbank (Oracle), die verschiedenen Module von GREAT-ER II tauschen 
über diese Daten aus. Für die DSS-Anwendung erfolgt der Datenaustausch
über das Dateisystem mittels definierter Tabellen im dBase-Format, da dieses
Format leicht zu Lesen und zu Schreiben ist.

Daher ist das GREAT-ER II Modellsystem um eine Datenschnittstelle zu
erweitern, die Zugriff auf dBase-Dateien definierter Struktur erlaubt
(s. Abschnitt \ref{sec:datenmodell}). Für eine zukünftige 
Kompatibilität des DSS mit GREAT-ER II soll der Modellkern selbst davon
unberührt bleiben. Der Modellkern ist bereits so implementiert, dass
durch definierte Schnittstellen verschiedene Bibliotheken angesprochen werden 
können, die jeweils auf unterschiedliche Datenquellen (Datenbank, Dateisystem,
...) zugreifen. Eine solche Bibliothek ist für den Zugriff auf dBase-Dateien zu
implementieren (vgl. Abschnitt \ref{sec:api-anforderungen}).

Der bisherige Modellansatz soll um diffusen Input in das Fliessgewässer
erweitert werden: Diffuse Einträge liegen als Werte zu einem 
mehrere Stretches umfassenden Catchment vor. Der Eintrag in einen 
Flussabschnitt berechnet sich aus dessen Anteil am Gesamteinzugsgebiet.

Das Datenmodell ist um die entsprechenden Strukturen zu erweitern, ebenso 
müssen neue Methoden zum einlesen der Daten definiert und implementiert werden.

Desweiteren muss der diffuse Input-Term in das Modellsystem integriert werden
(Abschnitt \ref{chap:modell-erweiterung}).

\section{Programmablauf}

Das eigentliche Modellsystem GREAT-ER (Modul GREAT-ERModel) ist in ein 
Python-Skript gekapselt, dass vom DSS aufgerufen wird und mit 
einem Status ja nach Abschluss der Simulation terminiert. 
Dieses Skript ist verantwortlich für 
\begin{itemize}
	\item das Anstoßen des Modellsystem, 
	\item die Überwachnung des Simulationsfortschritts und 
	\item das Schreiben der Ergebnisse nach Ende der Simulation.
\end{itemize}

Gleichzeitig wird eine API implementiert, die die vom Modellsystem benötigten
Methoden zum 
\begin{itemize}
	\item Einlesen der Simulationsdaten, 
	\item Schreiben der Simulationsergebnisse
\end{itemize}
bereitstellt.

Die Struktur der Ergebnis-Tabellen von GREAT-ER II liegt fest und ist für 
das DSS nur bedingt geeignet. Deshalb erfolgt eine Nachbereitung der Daten im 
oben bereits erwähnten Wrapper-Skript. Die Zwischenergebnisse der Simulation 
werden nach os.temp geschrieben.

Eine konkrete Simulation wird gesteuert über eine Konfigurationsdatei 
(simulini.dbf), die Pfade zu weiteren Datentabellen enthält:

\verb+python great-er-dss.py [config-file.dbf]+
\\

Die Struktur der Konfigurationsdatei (wie auch die einiger anderer im
Folgenden) besteht aus Schlüssel/Wert-Paaren, die im Programm eine leichte
Zuordnung erlauben, die die Dateien aber auch für den Entwickler oder 
Anwender lesbar und verständlich halten:
\\

\begin{tabular}{|l|l|p{6cm}|}
\hline
Schlüssel&Type&Description\\\hline
NAME & string(30,0) & Name des Parameters \\
VALUE & string(255,0) & Wert des Parameters als String \\
\hline
\end{tabular}
\\

Die folgenden Schlüssel müssen in der Konfigurationsdatei (im Weiteren
{\bf simulini.dbf}) gesetzt werden:
\\

\begin{tabular}{|l|l|}
\hline
Name & Beschreibung\\\hline
%
% FKoo: Wird in GREAT-ER II nicht mehr benötigt.
%  FIRST\_SEG & Erstes Segment (?? Wo steht das in GREAT-ER 2.0? Hier könnt
%  das u.U. noch geändert werden)\\
MODEL & Pfad zur model.dbf\\
RIVERNET & Pfad zur river.dbf\\
RIVERCLASS & Pfad zur rivclass.dbf\\
DISCH & Pfad zur disch.dbf\\
DISCHCLASS & Pfad zur dischclass.dbf\\
LOCAL\_DISCHARGE & Pfad zur local\_disch.dbf\\
EMISSION & Pfad zur emission.dbf\\
ENVIRONMENT & Pfad zur environmental.dbf\\
SUBSTANCE & Pfad zur substance.dbf\\
DIFFUSE\_INPUT & Pfad zur input\_diff.dbf\\
RES\_RIVER & Pfad zur res\_river.dbf\\
RES\_DISCH & Pfad zur res\_disch.dbf\\
\hline
\end{tabular}

Unter der Annahme, dass sich das betrachtete Einzugsgebiet nicht verändert,
können RIVERNET, RIVERCLASS, DISCH und DISCHCLASS als konstant angesehen
werden. Alle anderen Parameter können von zwischen den zwei Simulationen
variieren.

\clearpage

\section{Datenmodell}
\label{sec:datenmodell}

\subsection{Eingabedaten für das Simulationssystem}

Im Folgenden werden alle Dbase-Tabellen spezifiziert, die für das
greater-dss-Modell benötigt werden. 

\subsubsection*{model.dbf}

Parameter für die Modell-Einstellungen.
Diese Tabelle hat die gleiche Definition wie simulini.dbf.

\begin{tabular}{|l|l|}
\hline
Schlüssel & Beschreibung\\\hline
MC\_SHOTS & Anzahl Monte Carlo Shots \\
BG\_CONC & Hintergrund-Konzentration [mg/L] \\
MODE\_SEWER & Kanalisation: Modell-Modus\\
MODE\_AS & Belebtschlammkläranlage: Modell-Modus\\
MODE\_TF & Tropfkörperkläranlage: Modell-Modus\\
USE\_MONOD & Flagge für AS-Kläranlagenmodell Mode 2: Monod Kinetik verwenden.\\
MODE\_RIVER & River mode\\
USE\_DIFFUSE & Flagge für Flussmodell: Diffuser Input als weiterer Pfad.\\
PHOTODEG\_MODEL  & Flagge Fluss Mode 3: Photoabbau\\
SEDIMENT\_MODEL  & Flagge Fluss Mode 3: Sedimentation\\
VOLATIL\_MODEL   & Flagge Fluss Mode 3: Ausgasung\\
HYDROLYS\_MODEL  & Flagge Fluss Mode 3: Hydrolyse\\
BIODEGRAD\_MODEL & Flagge Fluss Mode 3: Bio-Abbau\\
USE\_BEHRENDT\_P & Flagge für Flussmodel: Abbaurate für wird pro Catchment angegeben\\
\hline
\end{tabular}

\subsubsection*{disch.dbf}

Daten der Punktquellen. Je Einleiter ein Record. 

\begin{tabular}{|l|l|l|l|p{5cm}|}
\hline
Feld&Type&Internal Name&Einheit&Beschreibung\\\hline
 ID      	& Int(26,0)	& DISCH\_ID && \\
 STRETCH\_ID  	& Int(26,0)	& - & -&\\
% CATCH\_ID	& Int(26,0)	& - &\\
 CLASS\_ID    	& Int(26,0)	& - & -&\\
 NAME        	& Char(255)	& - & - &\\
 POP         	& Char(13)	& - & cap & Number of people connected to the discharge.\\
 POP\_EQV      	& Char(13)	& - & cap & Population equivalent for industrial discharges\\
 DWF         	& Char(13)	& - & l/(cap*d)&Dry Weather Flow\\
 FLOW\_VAL    	& Char(40)	& - & $m^3/s$&Actual effluent flow\\
 FLOW\_DIST    	& Char(11)	& - & - & Flow Distribution Type\\
 FLOW\_DOM    	& Char(13)	& - & $m^3/s$ & Average domestic flow into discharge\\
 FLOW\_NONDO    & Char(13)	& - & $m^3/s$ &  Average non-domestic flow into discharge\\
 FLOW\_RUNOF    & Char(13)	& - & $m^3/s$& Average run-off flow into discharge\\
 TREATED	& Char(13)	& - & -& Treated fraction of discharge inflow.
\\
\hline
\end{tabular}

\subsubsection*{dischclass.dbf}

Allgemeine Daten, die für mehrere Einleiter (Klassen von Einleitern)
gelten.

\begin{tabular}{|l|l|l|l|}
\hline
Feld &Type&Einheit&Internal Name\\\hline
 ID          	& Int(26,0)	& -&  DISCH\_CLASS\_ID	\\
 NAME        	& char(255)	& -&  - \\
 WWTPTYPE    	& char(255)	& -&  WWTP\_TYPE \\
 CAPACITY    	& char(13)	& -&  - \\
 AER\_TYPE    	& char(13)	& -&  - \\
 H\_PRIM      	& char(13)	& -&  - \\
 OVERFL\_PRI  	& char(13)	& -&  V\_OVERFLOW\_PRIM \\
 R\_SS\_PRIM   	& char(13)	& -&  R\_SS\_PRIM\_MAX \\
 H\_SEC       	& char(13)	& -&  - \\
 OVERFL\_SEC  	& char(13)	& -&  V\_OVERFLOW\_SEC \\
 R\_SS\_SEC    	& char(13)	& -&  R\_SS\_SEC\_MAX \\
 SS\_ML       	& char(13)	& -&  - \\
 RECYCLE     	& char(13)	& -&  - \\
 A\_BIOMASS   	& char(13)	& -&  - \\
 H\_ACT\_SLDG  	& char(13)	& -&  H\_ACT\_SLUDGE \\
 B\_X         	& char(13)	& -&  - \\
 Y           	& char(13)	& -&  - \\
 DO          	& char(13)	& -&  - \\
 F\_AEROBIC   	& char(13)	& -&  - \\
 F\_ANOXIC    	& char(13)	& -&  - \\
 F\_ANAEROB  	& char(13)	& -&  F\_ANAEROBIC \\
 EPS\_N       	& char(13)	& -&  - \\
 EPS\_DN      	& char(13)	& -&  - \\
\hline
\end{tabular}


\subsubsection*{emission.dbf}

Optional, wenn für ausgewählte Punktquellen Einleitungsinformationen
abweichend von den allgemeinen Daten vorliegen. Liegen keine Daten vor,
sollte die Datei leer sein, aber exisitieren.

\begin{center}
\begin{tabular}{|l|l|l|l|p{5cm}|}
\hline
Feld&Type&Einheit&Internal Name&Beschreibung\\\hline
DISCH\_ID&Int (26,0)&-&-&\\
CONSUMPTN&string (40,0)&kg/(cap * a)&CONSUMPTION& Replaces regional substance average\\
PHI\_NONDOM& string(40,0)&kg/a&FLUX\_NONDOM& Additional chemical discharge from non-domestic point sources\\
PHI\_RUNOFF & string(40,0)&kg/a&FLUX\_RUNOFF& Additional chemical discharge from land runoff or other diffuse sources\\\hline
\end{tabular}
\end{center}

siehe auch Tabelle market\_tab, gleichnamige Attribute in der Oracle
Datenbank.

\subsubsection*{local\_disch.dbf}

Optional, wenn für ausgewählte Punktquellen Daten über Abbauleistungen ö.ä.
vorliegen, die von den allgemeinen Daten abweichen. Liegen keine Daten vor,
sollte die Datei leer sein, aber exisitieren. Die Beschreibungen
entsprechen denjenigen der Tabelle {\em disch.dbf} (s.o.).

\begin{center}
\begin{tabular}{|l|l|l|l|}
\hline
Feld&Type&Einheit&Internal Name\\\hline
 ID      	& Int(26,0)	& - & SESS\_DISCH\_ID \\
 STRETCH\_ID  	& Int(26,0)	& - & - \\
% CATCH\_ID	& Int(26,0)	& - \\
 CLASS\_ID    	& Int(26,0)	& - & - \\
 NAME        	& Char(255)	& - & - \\
 POP         	& Char(13)	& cap & - \\
 POP\_EQV      	& Char(13)	& cap & - \\
 DWF         	& Char(13)	& $m^3/s$ & - \\
 FLOW\_VAL    	& Char(40)	& $m^3/s$ & Wertepaar: Mean, Stddev \\
 FLOW\_DIST    	& Char(11)	& - & - \\
 FLOW\_DOM    	& Char(13)	& $m^3/s$ & - \\
 FLOW\_NONDO   & Char(13)	& $m^3/s$ & - \\
 FLOW\_RUNOF   & Char(13)	& $m^3/s$ & - \\
 TREATED	& Char(13)	& - & - \\
 R\_WWTP	& Char(13)	& - & - \\
\hline
\end{tabular}
\end{center}

\subsubsection*{input\_diff.dbf}

Optional, wenn diffuser Input gerechnet werden soll.

\begin{center}
\begin{tabular}{|l|l|p{6cm}|l|}
\hline
Feld &Type&Beschreibung&Einheit\\\hline
DIFF\_CATCH & Int(26,0) & Schlüssel für ein Parent catchment&-\\
DIFF\_INPUT & Float (11,4) & Diffuser Input der aus dem Parent catchment in
den Fluss geleitet wird.&kg/a\\
K\_P	&	Char(30)& Optional when der Mode USE\_BEHREND gerechnet
werden soll. Bezeichnet dann die Abbaurate im Fluss. & - \\\hline
\end{tabular}
\end{center}
Für diese Datei ist eine neue Methode zum Einlesen zu implemetieren, die über
die bisherige GREAT-ER II Spezifikation hinausgeht. Siehe dazu auch 
Abschnitt \ref{sec:api-anforderungen}.

\subsubsection*{river.dbf}

Daten der Abschnitte des Flussnetzwerks. Je Abschnitt ein Record.

Spezifikation wie in der  stretch\_tab in der Oracle Datenbank allerdings
ohne catch\_id, down1\_id und down2\_id. Dazu kommen folgenden zwei
Spalten:

\begin{center}
\begin{tabular}{|l|l|p{6cm}|l|}
\hline
Feld&Type & Beschreibung&Bereich\\\hline
DIFF\_CATCH & Int(26,0) & Referenzschlüssel zur ID des übergeordneten
Einzugsgebietes, aus dem die diffusen Einträge kommen.&-\\
DIFF\_FRAC & Char(13) & Prozentualer Anteil des Diffusen Inputs
aus dem Parent Catchment, der in den Stretch erfolgt.&[0,1]\\\hline
\end{tabular}
\end{center}

Gesamt:
\begin{center}
\begin{tabular}{|l|l|l|l|p{5cm}|}
\hline
Feld		&Type		& Einheit & Internal Name&Beschreibung\\\hline
 ID          	& Int(26)	& - & STRETCH\_ID &\\	 
 CLASS\_ID    	& Int(26)	& - & STRETCH\_CLASS\_ID& Stretch Class ID the stretch belongs to. \\
 UP\_1         	& Int(26)	& - & UP\_1\_ID& Network topology: First upstream stretch. \\
 UP\_2         	& Int(26)	& - & UP\_2\_ID &Network topology: Second upstream stretch.\\
 NAME        	& Char(255)	& - & - &Name (usually the river the stretch belongs to).\\
 TYPE        	& Char(11)	& - & - &Network topology: Stretch Type\\
 Q\_VAL       	& Char(40)	& $m^3/s$ & Wertepaar: Mean, Stddev&Volume flow.\\
 Q\_DIST       	& Char(11)	& - & -&Volume flow distribution. \\
 V\_VAL       	& Char(40)	& $m/s$ & Wertepaar: Mean, Stddev& Flow velocity.\\
 V\_DIST       	& Char(11)	& - & - & Flow velocity distribution.\\
 L           	& Char(40)	& m & - & Stretch Length.\\
 D\_VAL       	& Char(40)	& m & Wertepaar:Mean, Stddev &  Stretch depth.
\\
 D\_DIST       	& Char(11)	& - & - & Depth distribution.
\\
 DIFF\_CATCH	& Int(26)	& - & - & Catchment ID for diffusive Input\\
 DIFF\_FRAC	& Char(13)	& - & - & Fraction of total diffusive Input of
 corresponding catchment.\\
\hline
\end{tabular}
\end{center}

\subsubsection*{rivclass.dbf}

Allgemeine Daten, die für mehrere Flussabschnitte (Klassen von Abschnitten)
gelten.

\begin{center}
\begin{tabular}{|l|l|l|}
\hline
Feld		&Type		& Internal Name\\\hline
 ID          	& Int(26)	& STRETCH\_CLASS\_ID \\
 NAME        	& Char(255)	& - \\
 SS\_VAL      	& Char(40)	& - \\
 SS\_DIST      	& Char(11)	& - \\
 F\_OC        	& Char(13)	& - \\
 PH\_VAL      	& Char(40)	& - \\
 PH\_DIST      	& Char(11)	& - \\
 K\_Z         	& Char(13)	& - \\
 X           	& Char(13)	& - \\
 DO\_VAL      	& Char(40)	& - \\
 DO\_DIST      	& Char(11)	& - \\
 T\_W\_VAL	& Char(40)	& TEMP\_WATER\_VAL \\
 T\_W\_DIST	& Char(11)	& TEMP\_WATER\_DIST \\
 T\_A\_VAL   	& Char(40)	& TEMP\_AIR\_VAL \\
 T\_A\_DIST   	& Char(11)	& TEMP\_AIR\_DIST \\
 V\_SED       	& Char(13)	& - \\
 EPS\_SED     	& Char(13)	& - \\
 RHO\_SED     	& Char(13)	& - \\
 V10\_VAL	& Char(40)	& V\_WIND10\_VAL \\
 V10\_DIST	& Char(11)	& V\_WIND10\_DIST \\
\hline
\end{tabular}
\end{center}

Die nun folgenden Tabellen sind alle vom selben Aufbau, nämlich dreispaltig
mit
\begin{center}
\begin{tabular}{|l|l|p{6cm}|}
\hline
Name&Type&Description\\\hline
NAME & string(30,0) & Name des Parameters, entspricht der Field\_id in der
para\_tree\_def\_tab\\
VALUE & string(255,0) & Wert des Parameters als String. Der String besteht
entweder aus einer Zahl oder zwei mit Semikolon getrennten Zahlen.\\
DIST\_TYPE & string(11,0) & Verteilungstyp des Parameters\newline
0 = nicht verteilt\newline
1 = normal verteilt\newline
2 = log-normal verteilt\newline
3 = gleichverteilt\\\hline
\end{tabular}
\end{center}

Folgende Tabellen werden nach diesem Schema angelegt:
\subsubsection*{environmental.dbf}
mit folgenden Werten für 'NAME':
\begin{tiny}
\begin{verbatim}
        name         |        unit        |                               remark                               
---------------------+--------------------+--------------------------------------------------------------------
 F_OC_ML             |                    | organic carbon fraction of activated sludge solids
 RO_SS_ML            | kg / L             | ML solids density
 K_SORB_ML           | 1/h                | 1st order (de)sorption rate
 KGA_KLA             |                    | ratio of mass transfer rates in air/water
 R_END               | g(O2) / g(dwt) * h | activated sludge endogenous respiration rate
 ML_SALINITY         | mg(Cl) / L         | salinity of activated sludge ML
 PSI                 |                    | empirical constant for surface aeration
 TEMP_SEWAGE         | ?C                 | Sewage temperature
 TEMP_AIR            | ?C                 | Air temperature
 TEMP_AIR_RIVER      | C                  | Air temperature (overwrites river class settings)
 WIND_SPEED          | m/s                | Wind speed at 10 m height
 WIND_SPEED_RIVER    | m/s                | Wind speed at 10 m height (overwrites river class settings)
 H_AIR               | m                  | Air mixing height above ground
 TEMP_RIVER          | ?C                 | River water temperature
 K_SORB_PRIM         | 1/h                | 1st order (de)sorption rate
 A_PRIM              |                    | Effect of ratio Q/DWF on solids removal (empirical value).
 R_PRIM_BOD          |                    | Removal of BOD in a primary sedimentation tank
 R_PRIM_N            |                    | Removal of nitrogen in a primary sedimentation tank
 TEMP_CORR           |                    | correlation of temperature to flow (both air and water)
 SS_CORR             |                    | correlation of SS to flow
 DO_CORR             |                    | correlation of DO to flow
 BOD_CORR            |                    | correlation of BOD to flow
 K_SS_CORR           |                    | correlation of SS sedimentation rate to flow
 WIND_CORR           |                    | correlation of wind speed to flow
 K_SORB_SEC          | 1/h                | 1st order (de)sorption rate
 A_SEC               |                    | Effect of ratio Q/DWF on solids removal (empirical value).
 SS_SEWAGE           | g/m^3              | Suspended solids in sewage
 F_OC_SEWAGE         |                    | Organic carbon fraction of sewage solids
 RO_SS_SEWAGE        | kg / L             | Sewage (sewer) solids density
 PHI_CAP_BOD         | g / (cap * d)      | per capita production of BOD (PHI_CAP_BOD)
 PHI_CAP_N           | g / (cap * d)      | per capita production of nitrogen (PHI_CAP_N)
 COMBINED_SEWER_FLOW |                    | rain + waste water flow in sewers, as fraction of waste water flow
 CS_Q_DWF            |                    | Combined sewer flow as fraction of dry weather flow
 K_AIR               | m / s              | mass transfer coefficient (air)
 K_WATER             | m / s              | mass transfer coefficient (water)

\end{verbatim}
\end{tiny}

(siehe field\_id aus para\_tree\_def\_tab mit block\_id = 'ENV':
mit 
\begin{verbatim}
select field_id as name, unit,  remark from  para_tree_def_tab
where block_id = 'ENV';
\end{verbatim})

\subsubsection*{substance.dbf}
mit folgenden Werten für 'NAME':
\begin{tiny}
\begin{verbatim}
        name         |     unit      |                                     remark                                     
---------------------+---------------+--------------------------------------------------------------------------------
 K_STD_BIODEG        | L/(mg*h)      | Standard aerobic biodegradation rate (double first-order)
 K_DO                | mg/L          | Affinity constant for transition from aerobic to anaerobic processes.
 Q10                 |               | temperature correction for biodegradation
 A_ANAEROBIC         |               | Reduction of biodegradation rate under anaerobic conditions
 A_ANOXIC            |               | Reduction of biodegradation rate under anoxic conditions
 A_SORBED            |               | Reduction of biodegradation rate under adsorbed conditions
 K_MAX               | 1/h           | Monod: max. biodegradation rate
 Y                   | g[dwt]/g[BOD] | Monod: biomass yield
 K_S                 | mg/L          | Monod: affinity constant
 B                   | 1/h           | Monod: biomass decay rate
 NAME                |               | Common name of the substance
 CASNO               |               | Chemical Abstract Service number
 EINECSNO            |               | European Inventory of Existing Commercial Chemical Substances number
 SYNONYM             |               | Synonyms
 K_INSTREAM          | 1/h           | default in-stream removal rate
 K_DEG               | 1/h           | default degradation rate
 K_SED               | 1/h           | default SS settling rate
 K_VOL               | 1/h           | default volatilization rate
 K_PHOTO             | 1/h           | photolysis rate - near surface
 K_HYDR_A            | 1/h           | default hydrolysis rate - acid
 K_HYDR_B            | 1/h           | default hydrolysis rate - base
 K_HYDR_N            | 1/h           | default hydrolysis rate - neutral
 A_RIVER             |               | Increase or reduction of biodegradation rate under river conditions
 DEFAULT_CONSUMPTION | kg/(cap * a)  | Average domestic product consumption rate
 DEFAULT_CONSUMPTION_POP_EQV 
                     | kg/(cap * a)  | Average product consumption rate per population equivalent
 KD_RIVER            | L/kg[dwt]     | solids/liquid partitioning coefficient in river
 KD_SEWAGE           | L/kg[dwt]     | solids/liquid partitioning coefficient in sewage
 KD_ML               | L/kg[dwt]     | solids/liquid partitioning coefficient in mixed liquor
 H                   | Pa*m?/mol     | Henrys law constant
 MM                  | g/mol         | Molar mass.
 K_OW                | -             | Octanol/water partioning coefficient.
 K_OC                | cm^3/g        | Organic carbon / water partitioning coefficient.
 VP                  | Pa            | Vapor pressure
 WS                  | mg/L          | Water solubility
 PKA                 | -             | acid/base dissociation constant
 PROTOLYSIS          |               | Acid or base factor
 RISK_ASSESSMENT     |               | 
 PNEC_RIVER          | mg/L          | Predicted No-Effect Concentration (River)
 R_SEWER             | -             | chemical removal in sewers
 R_PRIMARY           | -             | chemical removal in primary settler
 R_ACTIVATED_SLUDGE  | -             | chemical removal in activated sludge plant
 R_TRICKLING_FILTER  | -             | chemical removal in trickling filter plant
 K_WWTP_NONBIO       | 1/h           | rate for non-biological degradation in WWTPs
 A_AS                | -             | Increase or reduction of biodegradation rate under activated sludge conditions
 K_AW                | -             | Dimensionless Henry's law constant.

\end{verbatim}
\end{tiny}
(siehe field\_id aus para\_tree\_def\_tab mit block\_id = 'SUBST'
mit 
\begin{verbatim}
select field_id as name, unit,  remark from  para_tree_def_tab
where block_id = 'SUBST';
\end{verbatim})
\clearpage

\subsection{Ausgabedaten des Simulationssystems}

\subsubsection*{res\_disch.dbf}

Der Simulationskern selbst schreibt (über da\_insert\_res\_disch())
einzelne Records in der Struktur

\begin{center}
\begin{tabular}{|l|l|l|}
\hline
Name&    Type& Inhalt	\\ \hline
RES\_DISCH\_ID & Number(26) & Key	\\
RES\_ID    	 & Number(26) & Key	\\
DISCH\_ID    	 & Number(26) & 	\\
FIELD\_ID    	 & Char(30)   & CSIMINFLUENT / CSIMEFFLUENT \\
BLOCK\_ID    	 & Char(30)   & 	\\
BLOCK\_RECNO     & Number(3)  & 	\\
VALUE    	 & Char(255)  & Wertepaar: Mean, Stddev \\
DIST\_TYPE    	 & Char(11)   & 2	\\
\hline
\end{tabular}
\end{center}

Diese müssen vom Wrapper umgesetzt werden auf eine Tabelle mit den Feldern.
Die Konzentrationen liegen in g/l vor. Sie werden berechnet als
Konzentration im Einlauf in die Kläranlage (CINF) sowie im Ausfluss der
Kläranalage (CEFF).
\begin{center}
\begin{tabular}{|l|l|p{6cm}|}
\hline
Name&Type&Description\\\hline
DISCH\_ID & Int(26)	& Referenz \\
CINF\_VAL & Char(40)	& Wertepaar \\
CINF\_DIST & Char(20)	& Verteilung \\
CEFF\_VAL & Char(40)	& Wertepaar \\
CEFF\_DIST & Char(20)	& Verteilung \\
\hline
\end{tabular}
\end{center}

\subsubsection*{res\_river.dbf}

Der Simulationskern selbst schreibt (über da\_insert\_bulk\_res\_stretch())
einzelne Records in der Struktur

\begin{center}
\begin{tabular}{|l|l|l|}
\hline
Name&    Type& Inhalt	\\ \hline
RES\_STRETCH\_ID & Number(26) & Key	\\
RES\_ID    	 & Number(26) & Key	\\
STRETCH\_ID    	 & Number(26) & 	\\
FIELD\_ID    	 & Char(30)   & CSIMSTART / CSIMINTERNAL / CSIMEND \\
BLOCK\_ID    	 & Char(30)   & 	\\
BLOCK\_RECNO     & Number(3)  & 	\\
VALUE    	 & Char(255)  & Wertepaar: Mean, Stddev \\
DIST\_TYPE    	 & Char(11)   & 2	\\
\hline
\end{tabular}
\end{center}

Diese müssen vom Wrapper umgesetzt werden auf eine Tabelle:
Die Konzentrationen liegen in g/l vor. Sie werden berechnet zu Beginn des
Riversegmenst (CSTRT), am Ende (CEND) und als Integral über den gesamten
Stretch (CINT)

\begin{center}
\begin{tabular}{|l|l|p{6cm}|}
\hline
Name&Type&Description\\\hline
STRETCH\_ID & Int(26)	& Referenz \\
CSTRT\_VAL & Char(40)	& Wertepaar \\
CSTRT\_DIST & Char(20)	& Verteilung \\
CINT\_VAL & Char(40)	& Wertepaar \\
CINT\_DIST & Char(20)	& Verteilung \\
CEND\_VAL & Char(40)	& Wertepaar \\
CEND\_DIST & Char(20)	& Verteilung \\
\hline
\end{tabular}
\end{center}

\clearpage

\section{API-Anforderungen}
\label{sec:api-anforderungen}
Folgende API-Funktionen werden benötigt:

\begin{center}
\tablefirsthead{%
	\hline
	API-Methode & Besonderheiten gegenüber GREAT-ER API \\\hline
}
\tablehead{%
	\hline
	\multicolumn{2}{|l|}{\small\sl Fortsetzung von vorheriger Seite}\\
	\hline
	API-Methode & Besonderheiten gegenüber GREAT-ER API \\\hline
}
\tabletail{%
	\hline
	\multicolumn{2}{|l|}{\small\sl Fortsetzung auf folgender Seite}\\
	\hline
}
\tablelasttail{%
	\\\hline
}
\begin{supertabular}{|l|p{9cm}|}
\multicolumn{2}{l}{Allgemein} \\
\hline
da\_db\_connect() &
	For DSS task 1 is defined slightly different: db\_instance
    is the path to the file simulini.dbf. It is checked
    whether the file exists and can be read. If so, it is read
    and the contents stored to be used by other API methods.
    Finally task 3 is done.
    Task 2 is not performed!
\\
\hline
da\_db\_disconnect() &
	For DSS, the class is just reinitialized. No clean-up actions.  \\
\hline
da\_db\_commit() &
	For DSS, the contents of res\_disch\_tab and res\_stretch\_tab are
	written to the corresponding dbase files (ie res\_disch.dbf
	and res\_river.dbf).  \\
\hline
da\_get\_version() & - \\
\hline
\multicolumn{2}{l}{Session} \\
\hline
da\_get\_sess() &
	For DSS, there is only exactly one session available which is
    temporary! \\
\hline
da\_update\_sess() &
	For DSS there is only exactly one session! Also, the modified date
    will not be set.  \\
\hline
\multicolumn{2}{l}{Model} \\
\hline
da\_get\_mod\_det() &
	 For DSS, there is only one dataset for model data.
     Hence, the MOD\_ID is ignored. Furthermore, DSS never requests
     a single record via MOD\_DET\_ID. Thus, always all records
     are returned and in case MOD\_DET\_ID is not -1, a RuntimeError
     is raised.  \\
\hline
\multicolumn{2}{l}{Results} \\
\hline
da\_delete\_res() &
	For DSS only exactly one result or none may exist. Hence,
	if there exists a result, this one is deleted regardless of res\_id. \\
\hline
da\_insert\_res() &
	For DSS, there is only exactly one results record. Hence,
    sess\_id is ignored (but still must be $>$ 1). res\_id will
    always be set to 1.  \\
\hline
da\_update\_res() &
	For DSS, there is only exactly one (or no) result.  \\
\hline
da\_insert\_res\_disch() &
	For DSS, task 2 is not performed since the para\_tree\_def\_tab
	does not exist for DSS. Also, the res\_disch\_id is not
	set since it is of no relevance for DSS.  \\
\hline
da\_insert\_bulk\_res\_stretch() &
	For DSS, task 2 is not performed since the para\_tree\_def\_tab
	does not exist for DSS. Also, the res\_stretch\_id's are
	of no relevance for DSS. \\
\hline
\multicolumn{2}{l}{Stretch} \\
\hline
da\_get\_stretch() &
	For DSS, catch\_id is ignored since there is only one catchment.
	Furthmore the only required return value is the full list
	of stretches. Hence any call with stretch\_id $<>$ -1 is reacted
	on with raising a RuntimeError.  \\
\hline
da\_get\_stretch\_class() &
	For DSS, the only required return value is the full list
	of stretch classes. Hence any call with stretch\_class\_id $<>$ -1
	reacted on with raising a RuntimeError.
					 \\
\hline
\multicolumn{2}{l}{Discharge} \\
\hline
da\_get\_disch() &
	For DSS, catch\_id is ignored since there is only one catchment.
    Furthmore the only required return value is the full list
    of discharges. Hence any call with disch\_id $<>$ -1 or stretch\_id $<>$
    -1 is reacted on with raising a RuntimeError.  \\
\hline
da\_get\_disch\_class() &
	 For DSS, the only required return value is the full list
     of discharge classes. Hence any call with disch\_class\_id $<>$ -1
     reacted on with raising a RuntimeError.  \\
\hline
da\_get\_market() &
	For DSS, catch\_id is ignored since there is only exactly one, but
    it must be $>$ 0 or otherwise a RuntimeError is raised.
    Furthermore, the only way this function is used is to get
    all of the records and therefore a RuntimeError is raised when
    disch\_id is not -1. market\_id is ignored.  \\
\hline
da\_get\_sess\_disch() &
	For DSS, catch\_id is ignored since there is only exactly one, but
    it must be $>$ 0 or otherwise a RuntimeError is raised.
    Furthermore, the only way this function is used is to get
    all of the records and therefore a RuntimeError is raised when
    disch\_id is not -1. sess\_disch\_id is ignored. \\
\hline
\multicolumn{2}{l}{Substance} \\
\hline
da\_get\_subst\_det() &
	  For DSS, there is only one dataset for environmental data.
      Hence, the SUBST\_ID is ignored. Furthermore, DSS never requests
      a single record via SUBST\_DET\_ID. Thus, always all records
      are returned and in case SUBST\_DET\_ID is not -1, a RuntimeError
      is raised.  \\
\hline
\multicolumn{2}{l}{Environment} \\
\hline
da\_get\_env\_det() &
	 For DSS, there is only one dataset for environmental data.
     Hence, the ENV\_ID is ignored. Furthermore, DSS never requests
     a single record via ENV\_DET\_ID. Thus, always all records
     are returned and in case ENV\_DET\_ID is not -1, a RuntimeError
     is raised.  \\
\hline
\multicolumn{2}{l}{Diffuse Input} \\
\hline
da\_get\_diffuse\_det() &
	Read in the table with diffuse input data, as described above.
	This method is not part of the GREAT-ER API specification,
	It is specific for DSS.
\end{supertabular}
\end{center}

\begin{verbatim}
\end{verbatim}

Darüber hinaus muss die API erweitert werden um Funktionen, die die
Parent Catchment spezifischen Daten auslesen und sie mit den Stretch-Daten
verbinden und um eine Funktion, die die Ergebnisse in Dbf-Dateien schreibt.

\chapter{Modell-Erweiterung}
\label{chap:modell-erweiterung}

Das bestehende GREAT-ER Modell basiert auf dem WATER-Modell\footnote{
vgl. Trapp/Matthies: Chemodynamics and Environmental Modeling, Springer, 1998,
S. 67 ff}. Lediglich die Abbaurate erster Ordnung wird in den verschiedenen
Komplexitätsstufen von GREAT-ER aus unterschiedlichen Modellen berechnet.

Das einfache Modell soll nun um externen Input erweitert werden. Dafür lässt
sich (nach Trapp/Matthies, S.12) folgende Differentialgleichung aufstellen:
\\

\begin{equation}
\frac{dC(t)}{dt} = \frac{I(t)}{V} - k C(t)
\end{equation} 
\medskip

\begin{tabular}{lll}
$C(t)$: & Konzentration 		& $[kg/m^3]$\\
$I(t)$: & Input 			& $[kg/s]$\\
$V$:	& Volumen des Fluss-Abschnitts	& $[m^3]$\\ 	
k:	& Abbau-Rate			& $[s^{-1}]$\\
\end{tabular}
\bigskip

Die allgemeine Lösung der Differentialgleichung für konstanten Input
($I(t)=const$) lautet:
\begin{equation}
C(t) = C_0 e^{-k t} + \frac{I}{V k} (1 - e^{-k t})
\end{equation}
\bigskip

GREAT-ER arbeitet statt mit Konzentrationen mit Massenflüssen. Dazu reicht es,
auf beiden Seiten mit dem Abfluss $Q=const$ zu multiplizieren:

\begin{equation}
\Phi(t) = \Phi_0 e^{-k t} + \frac{I Q}{V k} (1 - e^{-k t})
\end{equation}
\medskip

Es sind einige Sonderfälle zu betrachten:

$V=0$:
\begin{equation}
\Phi(t)= \Phi_0
\end{equation}

$k=0$:
\begin{equation}
\Phi(t) = \Phi_0 + \frac{I*Q}{V} 
\end{equation}

Abhängig vom betrachteten Fall ändert sich auch die Berechnung von 
$C_{sim, internal}$, definiert als das arithmetische Mittel der Konzentration
über die Aufenthaltszeit im Flussabschnitt:
\begin{eqnarray}
C_{internal} &=& \frac{1}{HRT} \cdot 
		 \int\limits_{t=0}^{t=HRT} C_{start} \cdot e^{-k\cdot t} dt 
			\nonumber\\ 
	     &=& \frac{C_{start}}{HRT}
			\left[ \frac{1}{-k}\cdot e^{-k\cdot t}\right]_0^{HRT} 
			\nonumber\\
	     &=& \frac{C_{start}}{k\cdot HRT}\left(1-e^{-k\cdot HRT}\right)
\end{eqnarray}

Für den Normalfall diffuser Einleitungen:
\begin{eqnarray}
C_{internal} &=& \frac{1}{HRT} \cdot 
		 \int\limits_{t=0}^{t=HRT} C_{start} \cdot e^{-k\cdot t} 
			+ \frac{I}{V\cdot k}\left(1-e^{-k\cdot t}\right)dt 
			\nonumber\\ 
	      &=& \frac{C_{start}}{HRT} \cdot 
		 \int\limits_{t=0}^{t=HRT} e^{-k\cdot t} dt 
		+ \frac{I}{HRT\cdot V\cdot k}
		\cdot\int\limits_{t=0}^{t=HRT}\left(1- e^{-k\cdot t}\right) dt 
		\nonumber\\
	      &=& \frac{C_{start}}{HRT} \cdot 
		 \int\limits_{t=0}^{t=HRT} e^{-k\cdot t} dt 
		- \frac{I}{HRT\cdot V\cdot k}
		\cdot\int\limits_{t=0}^{t=HRT}e^{-k\cdot t}dt
		+ \frac{I}{HRT\cdot V\cdot k}
		\cdot\int\limits_{t=0}^{t=HRT}dt
		\nonumber\\
	      &=&\frac{C_{start}}{HRT}
		    \left[ \frac{1}{-k}\cdot e^{-k\cdot t}\right]_0^{HRT}
		- \frac{I}{HRT\cdot V\cdot k}
		    \left[ \frac{1}{-k}\cdot e^{-k\cdot t}\right]_0^{HRT}
		+ \frac{I}{HRT\cdot V\cdot k}	
		    \left[ t \right]_0^{HRT}
		\nonumber\\
		\nonumber\\
	&=& \left(\frac{C_{start}}{HRT\cdot k} 
			- \frac{I}{HRT\cdot V\cdot k^2}
	    \right)\cdot\left(1-e^{-k\cdot HRT}\right)
	    +\frac{I}{V\cdot k}
\end{eqnarray}
\bigskip 

Im Sonderfall k=0 gilt laut Spezifikation des GREAT-ER II Modells
 $C_{internal} = C_{start}$.

Genauer betrachtet gilt hier:
\begin{eqnarray}
C_{internal} &=& \frac{1}{HRT}\cdot 
		 \int\limits_{t=0}^{t=HRT} C_{start} + \frac{I\cdot Q}{V} dt
		 	\nonumber \\
	      &=& \frac{1}{HRT}
			\cdot \left( C_{start} + \frac{I\cdot Q}{V}\right)
			\cdot \int\limits_{t=0}^{t=HRT} dt
			\nonumber \\
	      &=& C_{start} + \frac{I\cdot Q}{V}
\end{eqnarray}
D.h.: $C_{internal} = C_{end}$.
\label{theverylastpage}
\end{document}


