\documentclass[signature]{deltares_report}
\usepackage[titletoc]{appendix}


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

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

\newcommand{\ProgramName}{DAM kernel}
\newcommand{\ProgramNamePlusSpace}{DAM kernel }

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

\date{Jan. 2017}
\version{0.1}

\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.1}
\datei{Jan 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 standalone program \ProgramName, a software package for the automated calculation of the strength of dikes. DAM was developed by Deltares with and for STOWA for all water authorities.


\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
\ProgramNamePlusSpace - Architecture Overall \newline \citep{DAM_ArchitectureOverall} & Description of overall architecture of \ProgramNamePlusSpace and its components. \\ \hline
\ProgramNamePlusSpace- Functional Design \newline  \citep{DAMKernel_FunctionalDesign} & Description of the requirements and functional design. \\ \hline
\ProgramNamePlusSpace - Technical Design (this document) \newline \citep{DAMKernel_TechnicalDesign}& Description of the implementation of the technical design of \ProgramName. \\ \hline
\ProgramNamePlusSpace - Technical documentation \newline \citep{DAMKernel_TechnicalDocumentation} & Description of the arguments and usage of different software components, generated from in-line comment with Doxygen. \\ \hline
\ProgramNamePlusSpace - Test Plan \newline \citep{DAMKernel_TestPlan} & Description of the different regression and acceptation tests, including target values.  \\ \hline
\ProgramNamePlusSpace - Test Report \newline \citep{DAMKernel_TestReport} & Description of the test results (benchmarks and test scripts). \\ \hline
\end{tabular}
\caption{\small \ProgramNamePlusSpace system documents.}
\label{table-SystemDocuments}
\end{table}


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

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

\ProgramNamePlusSpace 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 \ProgramNamePlusSpace and its components.}
  \label{fig-DamComponents}
\end{figure}

The arrows illustrate the dependencies of the components.
 
\section{\ProgramNamePlusSpace components} \label{sec:DamKernelComponents}

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

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.

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

  \caption{\small \ProgramNamePlusSpace and its components.}
  \label{fig-DAMKernelComponents}
\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 \ProgramNamePlusSpace must provide progress information of the calculation, so clients of the kernel can show a progressbar
	\item The \ProgramNamePlusSpace 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 \ProgramNamePlusSpace 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 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.

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

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

\section{DSL} \label{sec:DSL}
The \ProgramNamePlusSpace 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 \ProgramNamePlusSpace 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-DAMKernelDataModelMain} 

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

  \caption{\small \ProgramNamePlusSpace main data model.}
  \label{fig-DAMKernelDataModelMain}
\end{figure}



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

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

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

  \caption{\small \ProgramNamePlusSpace kerenl Location object.}
  \label{fig-DAMKernelDataModelLocation}
\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{\ProgramNamePlusSpace main modules} \label{sec:DamKernelMainModules}

\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 specifi 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{\ProgramNamePlusSpace supporting modules} \label{sec:DamKernelSupportingModules}
\subsection{Failure mechanism wrappers}
These are calculation wrapper for each failure mechanism that is supported by the \ProgramName. Each wrapper should implement the IFailureMechanism interface.
\paragraph*{Macrostability inwards}
Calculation wrapper for Macrostability inward. Note that for each specific implementation of 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{Failure mechanism Calculation Runner}
This submodule calculates a specific failure mechanism by calling the IFailureMechanism interface of the wrapper implementation.
\subsection{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.
\subsection{Operation 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.
\subsection{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.
\subsection{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 \ProgramNamePlusSpace 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{Literature}  \label{chapterLiterature}

\bibliography{../DAM_references/dam_references}




\pagestyle{empty}
\mbox{}

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