\documentclass[signature]{deltares_report}
\usepackage[titletoc]{appendix}
\usepackage{lipsum}
%-----------------------------------------------

\begin{document}
\pagestyle{empty}
\cleardoublepage
%

\newcommand{\ProgramName}{DAM Engine\xspace}
\newcommand{\kernel}{failuremechanism kernel\xspace}

\title{\ProgramName}
\subtitle{Technical Design}
\projectnumber{1210702-000}
\client{Deltares - Geo engineering DKS}
\reference{1210702-000-GEO-0004}
\classification{-}

\date{Mar. 2017}
\version{0.2}

\keywords{Dike, safety assessment, design, software, macro stability, piping}

\references{Refer to \autoref{chapterLiterature}.}

\summary{This document contains the technical design for \ProgramName, an application that computes the strength of a complete dikering with respect to several failure mechnanisms, such as macro stability and piping.\\
\\
\textbf{\footnotesize{Samenvatting}} \\
Dit document bevat het technisch ontwerp voor \ProgramName, een User Interface applicatie die een gebruiker in staat stelt om voor een dijktraject berekeningen uit te voeren voor verschillende faalmechanismen, waaronder macrostabiliteit en piping.}

\versioni{0.2}
\datei{Mar 2017}
\authori{Tom The}
\revieweri{John Bokma}
\approvali{Maya Sule}

\status{draft}
\disclaimer{This is a draft report, intended for discussion purposes only. No part of this report may be relied upon by either principals or third parties.}

\deltarestitle


%------------------------------------------------------------------------------
\chapter{Introduction} 
\label{chapterIntroduction}

\section{Purpose and scope of this document} \label{sec:PurposeAndScope}

This document contains the technical design for the \ProgramName, a computational engine for the automated calculation of the strength of dikes.
DAM was developed by Deltares with and for STOWA for all water authorities.
This document describes the full intended architecture of the \ProgramName. 
What will actually will be implemented depends on the requirements of the clients using this \ProgramName.
If some functionality is not (yet) needed, then that part does not need to be implemented. 


\section{Other system documents} 
\label{sec:SystemDocuments}

The full documentation on the program comprises the following documents.

\renewcommand{\arraystretch}{1.3}

\begin{table}[H]
%\caption{xxx}
%\label{xxx}
\begin{tabular}{|p{40mm}|p{\textwidth-40mm-24pt}|} \hline
\textbf{Title} & \textbf{Content} \\ \hline
\ProgramName - Architecture Overall \newline \citep{DAM_ArchitectureOverall} & Description of overall architecture of the \ProgramName and its components. \\ \hline
\ProgramName- Functional Design \newline  \citep{DAMEngine_FunctionalDesign} & Description of the requirements and functional design. \\ \hline
\ProgramName - Technical Design (this document) \newline \citep{DAMEngine_TechnicalDesign}& Description of the implementation of the technical design of \ProgramName. \\ \hline
\ProgramName - Technical documentation \newline \citep{DAMEngine_TechnicalDocumentation} & Description of the arguments and usage of different software components, generated from in-line comment with Doxygen. \\ \hline
\ProgramName - Test Plan \newline \citep{DAMEngine_TestPlan} & Description of the different regression and acceptation tests, including target values.  \\ \hline
\ProgramName - Test Report \newline \citep{DAMEngine_TestReport} & Description of the test results (benchmarks and test scripts). \\ \hline
\end{tabular}
\caption{\small \ProgramName system documents.}
\label{table-SystemDocuments}
\end{table}

\section{Document revisions}
\label{sec:DocumentRevisions}
\subsection{Revision 0.1}
\label{sec:Revision01}
First concept of the document.

\subsection{Revision 0.2}
\label{sec:Revision02}
Adapted based on reviews of this document by Jan Noort and Andr\'e Grijze.

%------------------------------------------------------------------------------
\chapter{System Architecture} \label{chapterSystemArchitecture}

\section{DAM components} \label{sec:DamComponents}

\ProgramName is part of the whole DAM system that contains several components. 
Please see \autoref{fig-DamComponents} for an overview of the components of DAM. 
In \citep{DAM_ArchitectureOverall} a description of the overall architecture of the DAM system can be found.

\begin{figure}[H]
  \begin{center}
    \includegraphics[width=15cm]{pictures/DamComponents.pdf}
  \end{center}

  \caption{\small \ProgramName and its components.}
  \label{fig-DamComponents}
\end{figure}

The arrows illustrate the dependencies of the components.

\section{\ProgramName data flow}
\label{sec:ProgramNameDataFlow}
Please see \autoref{fig-DAMMainDataflow} for an overview of the data flow within the DAM system. 

\begin{figure}[H]
  \begin{center}
    \includegraphics[width=15cm]{pictures/DAMMainDataflow.pdf}
  \end{center}

  \caption{\small \ProgramName and its components.}
  \label{fig-DAMMainDataflow}
\end{figure}
 
The red arrows illustrate the dataflow between the main DAM components. \newline
As can be seen the data exchange between the \ProgramName and the \kernel (bottom of the picture) is done through the API that is defined by the \kernel.
The data exchange between the \ProgramName and the DAM client (top of the picture) is done through XML files (one for input and one for output), which are well defined by XML schemas (XSD's).
\section{\ProgramName components} 
\label{sec:DAMEngineComponents}

The \ProgramName itself also consists of several modules.
These can be seen in see \autoref{fig-DAMEngineComponents} 

All of the submodules inside the Main Modules are completely independent.
All of the submodules inside the Supporting Modules are also independent. 
But all these submodules can be used by each of the main modules. 
The arrows show the allowed dependencies.

\begin{figure}[H]
  \begin{center}
    \includegraphics[width=16cm]{pictures/DAMEngineComponents.pdf}
  \end{center}

  \caption{\small \ProgramName and its components.}
  \label{fig-DAMEngineComponents}
\end{figure}

\section{\ProgramName sequence and activity diagrams} \label{sec:DAMEngineSequenceActivityDiagrams}
In this section the sequence diagrams, showing the use of the submodules are shown. 
For each sequence diagram a corresponding activity diagram is also shown

\subsection{Assessment}
\begin{figure}[H]
  \begin{center}
    \includegraphics[width=15cm]{pictures/DAMEngineSequenceAssessment.pdf}
  \end{center}
  \caption{\small \ProgramName Assessment sequence diagram.}
  \label{fig-DAMEngineSequenceAssessment}
\end{figure}

\begin{figure}[H]
  \begin{center}
    \includegraphics[width=8cm]{pictures/DAMEngineActivityAssessment.pdf}
  \end{center}
  \caption{\small \ProgramName Assessment activity diagram.}
  \label{fig-DAMEngineActivityAssessment}
\end{figure}

\subsection{Assessment Regional}
\begin{figure}[H]
  \begin{center}
    \includegraphics[width=15cm]{pictures/DAMEngineSequenceAssessmentRegional.pdf}
  \end{center}
  \caption{\small \ProgramName Regional assessment sequence diagram.}
  \label{fig-DAMEngineSequenceAssessmentRegional}
\end{figure}

\begin{figure}[H]
  \begin{center}
    \includegraphics[width=8cm]{pictures/DAMEngineActivityAssessmentRegional.pdf}
  \end{center}
  \caption{\small \ProgramName Regionl assessment activity diagram.}
  \label{fig-DAMEngineActivityAssessmentRegional}
\end{figure}

\subsection{Design}
\begin{figure}[H]
  \begin{center}
    \includegraphics[width=15cm]{pictures/DAMEngineSequenceDesign.pdf}
  \end{center}
  \caption{\small \ProgramName Design sequence diagram.}
  \label{fig-DAMEngineSequenceDesign}
\end{figure}

\begin{figure}[H]
  \begin{center}
    \includegraphics[width=8cm]{pictures/DAMEngineActivityDesign.pdf}
  \end{center}
  \caption{\small \ProgramName Design activity diagram.}
  \label{fig-DAMEngineDesignAssessment}
\end{figure}
%------------------------------------------------------------------------------
\chapter{Architectural Choices} \label{chapterArchitecturalChoices}

\section{Design principles} \label{sec:DesignPrinciples}
\begin{itemize}
	\item No circular references between objects. 
	When it is really unavoidable, then do it through a generic interface (e.g.\ IParentObject)
	\item The calculation will support parallellization. 
	So do not use global variables and avoid using statics.	
	\item Failure mechanisms will be connected through wrapper classes, which will share a common IFailureMechanism interface
	\item Surfaceline adapter classes will share a common ISurfacelineAdapter interface
	\item The \ProgramName must provide progress information of the calculation, so clients of the \ProgramName can show a progressbar
	\item The \ProgramName must provide the possiblity to abort a calculation within a reasonable timespan.
	\item There should be no User Interface elements shown anytime during the calculation.
\end{itemize}

\section{Programming environment} \label{sec:ProgrammingEnvironment}
The \ProgramName will be developed in C\# with the .NET 4.5 framework. The development environment will be Visual Studio 2015.

\section{Error handling} \label{sec:ErrorHandling}
Errors within the \ProgramName are handled through the standard exception handling of the .NET framework. Error messages must contain as much information as possible, so a user can trace back the error to the input data. \newline
Errorhandling with a \kernel is done through the mechanism that is supplied by the API of the specific kernel. \newline
Errorhandling with DAM Client is done by passing the error messages as part of the ouput XML file. \newline
In fact it is the same mechanism that is used for exchanging the regular data (input and output), as shown in \autoref{fig-DAMMainDataflow}. 
 

\section{External libraries and components} \label{sec:ExternalLibrariesAndComponents}
\ProgramName uses third-party libraries and components. Only open sources and free components, that are free to redistribute are allowed to be used. 

Furthermore \ProgramName uses the Delta Shell Light (DSL) library, that is developed by Deltares.

\section{DSL} \label{sec:DSL}
The \ProgramName only uses part (the non-UI modules) of the DSL library
\begin{itemize}
	\item DSL-Core
	\item DSL-Probabilistic
	\item DSL-Geo
\end{itemize}

\section{Other libraries} \label{sec:OtherLibraries}
Other libraries that are used bij the \ProgramName are:
\begin{itemize}
	\item Math.Net: mathematical library
\end{itemize}




%------------------------------------------------------------------------------
\chapter{Data Model}  \label{chapterDataModel}

\section{Main Data Model} \label{sec:MainDataModel}

The main data model can be seen in see \autoref{fig-DAMEngineDataModelMain} 

\begin{figure}[H]
  \begin{center}
    \includegraphics[width=15cm]{pictures/DAMEngineDataModelMain.pdf}
  \end{center}

  \caption{\small \ProgramName main data model.}
  \label{fig-DAMEngineDataModelMain}
\end{figure}



\section{Location} \label{sec:Location}

The data model of the Location class can be seen in see \autoref{fig-DAMEngineDataModelLocation} 

\begin{figure}[H]
  \begin{center}
    \includegraphics[width=12cm]{pictures/DAMEngineDataModelLocation.pdf}
  \end{center}

  \caption{\small \ProgramName Location object.}
  \label{fig-DAMEngineDataModelLocation}
\end{figure}




%------------------------------------------------------------------------------
\chapter{Data Description}  \label{chapterDataDescription}

\section{Type enumerations} \label{sec:TypeEnumerations}
\subsection{MainMechanismType}
\begin{itemize}
	\item Stability
	\item Piping
\end{itemize}

\section{Main Data Model} \label{sec:MainDataModelDescription}

\subsection{Input}
\paragraph*{DamProjectType}
\begin{itemize}
	\item Assessment
	\item Design
	\item Operational
\end{itemize}
\paragraph*{DamProjectCalculationSpecification}
This class specifies which failuremechanism is to be calculated and it also contains the specific options for the selelected mechanism (e.g.\ which calculation model)
\paragraph*{Locations}
This is a collection of locations, with each location containing the location specific data.
\paragraph*{Soil Segments}
This is a collection of soil segments, with each segment containing the subsoil data for a specific failure mechanism.\textbf{}
\paragraph*{Soils}
This is a collection of soils, with each soil containing the soil parameters needed for the calculation of all failure mechanisms.\textbf{}

\subsection{Output}
\paragraph*{CalculationResults}
A calculation result holds the result for a specific location, a specific failure mechanism, and a specific subsoil scenario of a specific segment defined in the location data.
\paragraph*{CalculationMessages}
These are all the message that are generated by the calculation. A message must containt as much information as possible to trace back the information tho the input data (e.g.\ a specific location, a specific failure mechanism, and a specific subsoil scenario of a specific segment defined in the location data).

\section{Location} \label{sec:LocationDescription}
\paragraph*{SoilSegment}
A soil segment contains the subsoil data for a specific failure mechanism
\paragraph*{SurfaceLine}
A surfaceline is describes the dike profile in a specific location. In the Design calculation it can also be the new dike profile, which can meet design creteria in a specific load scenario.
\paragraph*{WaternetOptions}
The options that support the creation of a waternet in a specific location.
\paragraph*{DesignOptions}
The options that will be used in the Design calculation (e.g.\ how to design a shoulder when needed).
\paragraph*{SensorData}
The sensor data can be used to define a waternet based on live sensor data. This sensor data holds information about ID and location of the sensor. The actaul sensor readings are defined as timeseries readings for each sensor in each location.
\paragraph*{LoadScenario}
Used for Design calculation. A load scenario contains the following items:
\begin{itemize}
	\item Riverlevel low
	\item Riverlevel high
	\item Dike table height
	\item Required safety factor for each specified failure mechanism
	\item Uplift criterium for each specified failure mechanism
	\item Waternet options for each specified failure mechanism
\end{itemize}
\paragraph*{IFailureMechanismOptions}
Specific options for each location for each failure mechanism.
%------------------------------------------------------------------------------
\chapter{Module Description}  \label{chapterModuleDescription}

\section{\ProgramName main modules} \label{sec:DAMEngineMainModules}

\subsection{Assessment Regional Dikes}
This module performs an assessment for regional dikes.
\paragraph*{Regional assessment calculation}
This is the main submodule of the regional assessement. 
This submodule contains the main loop of the calculation.
\paragraph*{Regional scenario selector}
This submodule generates all the scenarios that have to be evaluated for a specific location. 
The scenarios are selected based on the local conditions.
\paragraph*{Regional schematization factor calculator}
This submodule calculates the schematization factor in a location based on all results of all scenarios in a location.
\subsection{Assessment Primary Dikes}
This module performs an assessment for primary dikes.
\paragraph*{Primary assessment calculation}
This is the main submodule of the primary assessement. 
This submodule contains the main loop of the calculation.
\subsection{Design Primary Dikes}
This module performs an design calculation for primary dikes.
\paragraph*{Primary design calculation}
This is the main submodule of the primary design calculation. 
This submodule contains the main loop of the calculation.
\subsection{NWO Calculation}
This module performs an NWO (Niet Waterkerende Objecten) calculation for primary dikes.
\paragraph*{Primary NWO calculation}
This is the main submodule of the NWO calculation. 
This submodule contains the main loop of the calculation.

\section{\ProgramName supporting modules} \label{sec:DAMEngineSupportingModules}
\subsection{Failure mechanism wrappers}
These are calculation wrappers for each kernel to be implemented for each failure mechanism that is supported by the \ProgramName. 
Each wrapper should implement the IFailureMechanism interface.\newline
Example:
Lets say that for the failure mechanism piping we have 3 kernels: Bligh, Sellmeijer and VNK. 
Then for each of these kernels a calculation wrapper has to be written.\newline
Another example: 
D-Geo Stability kernel has the ability to calculate the failure mechanism macrostability inwards en the failure mechanism macrostability outwards. 
In this case 2 wrappers (one for each failure mechanism) are needed for this single kernel.
\paragraph*{Macrostability inwards}
Calculation wrapper for Macrostability inward. 
Note that (as already mentioned above) for each specific kernel implementation for a failure mechanism, a separate wrapper has to be build (e.g.\ Slope/W and D-Geo Stability)
\paragraph*{Macrostability outwards}
Calculation wrapper for Macrostability outward.
\paragraph*{Piping}
Calculation wrapper for Piping.
\subsection{Surfaceline adapters}
A collection of surfaceline adapters to support the design calculation. 
Each adapter should adhere to the ISurfaceLineAdapter interface.
\paragraph*{Surfaceline Adapter Height}
Adapts the surfaceline by adding extra height to the dike crest.
\paragraph*{Surfaceline Adapter Slope}
Adapts the surfaceline by changing the slope of the dike on the inside.
\paragraph*{Surfaceline Adapter Shoulder}
Adapts the surfaceline by adding a shoulder or enlarging the shouldeer on the inside of the dike.
\paragraph*{Surfaceline Adapter NWO}
Adapts the surfaceline by adding a NWO on a specifi place in the surfaceline.
\subsection{Calculation Runner}
\paragraph*{Failure mechanism Calculation Runner}
This submodule calculates a specific failure mechanism by calling the IFailureMechanism interface of the wrapper implementation.
\paragraph*{Design Calculation Runner}
This submodule performs a design calculation for a specific failure mechanism by calling the IFailureMechanism interface and several surfaceline adapters through their  ISurfacelineAdaptert interface.
\paragraph*{Operational Calculation Runner}
This submodule can perform a calculation based on sensor readings (as time-series). 
The load on the systems (the waternet) will be based on those sensor readings. This can be used in operational systems like DamLive.
\paragraph*{Probabilistic Calculation Runner}
This submodule performs a probabilistic calculation for a specific location and failure mechanism. 
The outcome is a failure probability for that location and failure mechanism. 
\subsection{General submodules}
\paragraph*{Geometry creator}
This submodule combines a surfaceline with a subsoil scenario. 
The output is a gemetry that can be used by the failure mechanisms to perform a calculation.
\paragraph*{Waternet creator}
This submodule determines the waternet that will be used by the failure mechanisms. 
At first only the DAM implementation will be used as a waternet creator. 
Later on new implementations can be made. 
E.g.\ specific for each failure mechanism, or an implementation based on a numerical model like DgFlow.
\subsection{Scripting engine}
To enable advanced users to experiment with how the \ProgramName works a Python scripting engine is implemented as a submodule. 
The scripting engine has acces to the data model and the submodules through well defined interfaces. 

%------------------------------------------------------------------------------
\chapter{Programing Interface}  \label{chapterProgramingInterface}
This is the definition of the programming interface. 
The only way to communicate to the \ProgramName is through this interface.

\textbf{TO DO: Add interface description}

%------------------------------------------------------------------------------
\chapter{Literature}  \label{chapterLiterature}

\bibliography{../DAM_references/dam_references}




\pagestyle{empty}
\mbox{}

%------------------------------------------------------------------------------
\end{document}
