\documentclass[signature]{deltares_report}
\usepackage{listings}
\usepackage[titletoc]{appendix}
\usepackage{lipsum}
%-----------------------------------------------
\lstset{ %
  basicstyle=\footnotesize,        % the size of the fonts that are used for the code listings
}

\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{Jun. 2017}
\version{0.3}

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

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

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

\versioni{0.3}
\datei{Mar 2017}
\authori{Tom The}
\revieweri{John Bokma \newline Andr\'e Grijze}
\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. 

\subsection{Future options}
\label{sec:FutureOptions}
As mentioned above this document contains some options that will not be implemented in the first release, but are foreseen to be implemented in the near future. Therefore although sometimes a reference will be made to these options, these will not be described in detail yet.

That applies in particular to the following subjects:
\begin{itemize}
	\item NWO module("Niet Waterkerende Objecten")
	\item WBI failure mechanisms (Piping, Macrostability)
\end{itemize}
\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
Architecture Guidelines \newline \citep{ArchitectureGuidelines} & Architecture guidelines that are used by DSC-Deltares. \\ \hline
\end{tabular}
\caption{\small \ProgramName system documents.}
\label{table-SystemDocuments}
\end{table}

\section{Document revisions}

\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.

\subsection{Revision 0.3}
\label{sec:Revision03}
Adapted based on review of this document by John Bokma.

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

This chapter contains diagrams describing the modules and submodules of the \ProgramName and how they interact. 
In \autoref{chapterModuleDescription} a short description of each module/submodules is given.

\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{Dikes 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{Dikes 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=9cm]{pictures/DAMEngineActivityAssessmentRegional.pdf}
  \end{center}
  \caption{\small \ProgramName Regional assessment activity diagram.}
  \label{fig-DAMEngineActivityAssessmentRegional}
\end{figure}

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

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

\subsection{Dikes 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}

\subsection{Dikes NWO calculation}
This will not be part of the first implementation of \ProgramName and therefor this paragraph has not yet been written.

%------------------------------------------------------------------------------
\chapter{Architectural Choices} \label{chapterArchitecturalChoices}
\section{Architecture guidelines}
\label{sec:ArchitectureGuidelines}

Within Deltares, DSC, a document is being written about Archtitecture Guidelines \citep{ArchitectureGuidelines}. 
Although it is still a work in progress \ProgramName should adhere to those guidelines.
More specific guidelines are added in the following sections of this chapter.

\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 designer classes will share a common ISurfacelineDesigner 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 output 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}. 
\newline
\newline
The \ProgramName should be able to issue the error messages in different languages.
In the first implementation only the 2 following languages will be supported:
\begin{itemize}
	\item Dutch (NL)
	\item English (US)
\end{itemize}
For translations, the standard Windows mechanism with language resource dll's will be used. 
Note: the current implementation of DAM uses another mechanism for translations, that will not be applied here, because it is dependent on the DSL (Delta Shell Light) library, which will not be used for the \ProgramName. 

\section{Libraries and components} \label{sec:ExternalLibrariesAndComponents}
\ProgramName uses other libraries and components. 

For now we foresee only the use of the following libraries:
\begin{itemize}
	\item Failure mechanisms.
	\item Math.NET.
\end{itemize}
Other libraries may be used under the condition that they are open source and free components, that are free to redistribute. \newline
All libraries should be listed in a manifest accompanying the release of \ProgramName. The list should also specify under which license each specific library is distributed. 

Note: the current implementation of DAM uses the DSL (Delta Shell Light) library. This library will explicitly not be used for the \ProgramName, because this library is being made obsolete. 


\subsection{Failure mechanisms} \label{sec:FailureMechanisms}
The failure mechanisms are treated as external libraries. 
Some failure mechanisms were part of the source of the original DAM program. 
With the new architecture of \ProgramName this will longer be the case. 
These failure mechanisms will be placed in a DAM failure mechanisms library, that is not part of \ProgramName anymore.
The following failure mechanisms are currently supported by the original DAM program:
\begin{itemize}
	\item Piping Bligh  (not opensource)
	\item Piping Sellmeijer VNK  (not opensource)
	\item Piping Sellmeijer 2 forces  (not opensource)
	\item D-Geo Stability inward (not opensource, but commerical)
	\item D-Geo Stability outward (not opensource, but commerical)
\end{itemize}

After the original failure mechanisms have been implemented, the new WBI failure mechanisms will be added:
\begin{itemize}
	\item WTI Piping
	\item WTI Macrostability inward
\end{itemize}

\subsection{Math.Net} \label{sec:MathNet}
Math.Net is a library that is distributed under the MIT/X11 license. Therefore it meets the conditions about open source and free redistribution.


%------------------------------------------------------------------------------
\chapter{Data Model}  \label{chapterDataModel}
This chapter contains diagrams describing the main data objects of the \ProgramName and their relation to each other. 
In \autoref{chapterDataDescription} a short description of these data objects is given.

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

The main data model can be seen in see \autoref{fig-DAMEngineDataModelMain} 
It is not fully worked out, but just a global overview. 
The details will be filled in when programming the \ProgramName. 
This is because we do not intend to write a big upfront design.
\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 Macrostability inward
	\item Macrostability outward
	\item Piping
\end{itemize}

\section{Scenarios} \label{sec:Scenarios}
Scenarios are widely (a)bused within DAM. It is good to define in which context scenarios are used and how they are to be called. Simply using the word scenario is not enough.
Within DAM we have 3 types of scenarios:
\begin{itemize}
	\item Subsoil scenario
	\item Design scenario
	\item Regional scenario
\end{itemize}

\subsection{Subsoil scenario}
\label{sec:SubSoilScenario}
Used as part of the stochastic subsoil schematization. 
A subsoil scenario defines a possible 1D- or 2D-profile that applies to a certain location.

\subsection{Design scenario}
\label{sec:DesignScenario}
Used for Design calculation. 
In a design calculation a new surfaceline is designed for a location, based on a target failure factor (e.g. due to new requirements), or load (e.g. a higher waterlevel).

\subsection{Regional scenario}
\label{sec:RegionalScenario}
For regional assessments there are certain scenarios that have to be evaluated, depending on the circumstances (e.g. drought, type of dike etc.). Part of the assessment is the determination which scenarios have to be evaluated and then calculating those scenarios.

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

\subsection{Input}
\paragraph*{DamProjectType}
\begin{itemize}
	\item Assessment
	\item Assessment regional
	\item Operational
	\item Design
	\item NWO
\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 contain 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 describes the dike profile in a specific location. In the Design calculation it can also be the new dike profile, which can meet design criteria in a specific design 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 actual sensor readings are defined as timeseries readings for each sensor in each location.
\paragraph*{DesignScenario}
Used for Design calculation. A design 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 Dikes}
This module performs an assessment for general dikes (e.g. 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{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{Design Dikes}
This module performs an design calculation for all types of 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{Operation module}
This module performs a time series based calculation for all types of dikes.
\paragraph*{Time series based calculation}
This is the main submodule of the time series based 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 wrapper interface}
For each \kernel  a specific wrapper will be written. This wrapper must implement a specific interface, so the \ProgramName can support the use of the \kernel. 
The interface that must be implemented is IFailureMechanism.\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 and the failure mechanism macrostability outwards. 
In this case 2 wrappers (one for each failure mechanism) are needed for this single kernel.\newline
The next methods are defined in the IFailureMechanism interface
\begin{itemize}
	\item Prepare()
	\item Validate()
	\item Execute()
	\item Design()
	\item PostProcess()
	\item RegisterProgressFeedback()
	\item RegisterAbortCheck()
\end{itemize}

\subsubsection{Prepare}
\label{sec:Prepare}
The purpose of this method is to fill a dataobject that implements the IKernelDataInput interface. This dataobject will be needed for the other methods in this interface.  
This method has one parameter:
\begin{itemize}
	\item Input
\end{itemize}
It returns IKernelDataInput. This method fills the IKernelDataInput object from the main input data object (Input).
In IKernelDataInput the data is filled that is needed by the specific \kernel data. 
Each \kernel wrapper will have its own implementation of IKernelDataInput.

\subsubsection{Validate}
\label{sec:Validate}
The purpose of this method is to validate the data that will be used as input for the failure mechanism.
This method has 2 parameters:
\begin{itemize}
	\item IKernelDataInput (kernel input data) 
	\item ValidationMessageList (a list of messages produced by the validation)
\end{itemize}
It returns an integer:
0: no errors. A calculation is possible. It is possible that there are warning messages.
>0: number of error messages that prevent a calculation.

\subsubsection{Execute}
\label{sec:Execute}
This method performs the actual calculation of the failure mechanism,
This method has 2 parameters:
\begin{itemize}
	\item IKernelDataInput (kernel input data) 
	\item ErrorMessageList (a list of error messages produced by the calculation)
\end{itemize}
It returns IKernelDataOutput. IKernelDataOutput contains the calculation results of the \kernel data. 
Each \kernel wrapper will have its own implementation of IKernelDataOutput.

\subsubsection{Design}
\label{sec:Design}
This method implements a design calculation. Based on certain design parameters (e.g. target failure factor, new load parameters, design strategies, etc.) a new design is made for the input data (e.g. a new surfaceline).
This method has 3 parameters:
\begin{itemize}
	\item IKernelDataInput (kernel input data) 
	\item IKernelDesignDataInput (definition of the design parameters) 
	\item ErrorMessageList (a list of error messages produced by the design calculation)
\end{itemize}
It returns a IKernelDesignDataOutput. IKernelDesignDataOutput contains the adapted input data (a.g. a new designed surfaceline) and other design results (e.g. number of iterations needed, success or failure etc.). \newline
Based on the given criteria a new design is determined, which will meet the required criteria. If such a design is not possible, that will be reported back.


\subsubsection{PostProcess}
\label{sec:PostProcess}
This method has 2 parameters
\begin{itemize}
	\item IKernelDataOutput (kernel output data) 
	\item Output (the \ProgramName output data)
\end{itemize}
This method fills the \ProgramName Output object with the results of the \kernel (IKernelDataOutput).
\subsubsection{RegisterProgressFeedback}
\label{sec:RegisterProgressFeedback}
This method registers a callback function into the \kernel wrapper that can report back progress status from the \kernel wrapper to the calling application. The calling application provides the callback function that should be called.
\subsubsection{RegisterAbortCheck}
\label{sec:RegisterAbortCheck}
This method registers a callback function into the \kernel wrapper. The calling application provides the callback function that should be called. If the function reports back that an abort was requested, the \kernel should abort the calculation and return to the calling application with an appropriate error message.

\subsection{Failure mechanism wrapper implementations}
For now the next three implementations of failure mechanism wrappers are foreseen. In the future more can be added. Note also that for a specific failure mechanism multiple implementations can be created. E.g. Piping: 
\begin{itemize}
	\item piping Bligh
	\item piping Sellmeijer 2 forces
	\item piping Sellmeijer 4 forces
	\item piping VNK model
\end{itemize}

\subsubsection*{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)
\subsubsection*{Macrostability outwards}
Calculation wrapper for Macrostability outward.
\subsubsection*{Piping}
Calculation wrapper for Piping.
\subsection{Surfaceline designers}
A collection of surfaceline designers to support the design calculation. 
Each designer should adhere to the ISurfaceLineDesigner interface.
\subsubsection*{Surfaceline Designer Height}
Adapts the surfaceline by adding extra height to the dike crest.
\subsubsection*{Surfaceline Designer Slope}
Adapts the surfaceline by changing the slope of the dike on the inside.
\subsubsection*{Surfaceline Designer Shoulder}
Adapts the surfaceline by adding a shoulder or enlarging the shoulder on the inside of the dike.
\subsubsection*{Surfaceline Designer NWO}
Adapts the surfaceline by adding a NWO on a specific place in the surfaceline.
\subsubsection{Calculation Runner}
\paragraph*{Failure mechanism Calculation Runner}
This submodule calculates a specific failure mechanism by calling the IFailureMechanism interface of the wrapper implementation.
\subsubsection*{Design Calculation Runner}
This submodule performs a design calculation for a specific failure mechanism by calling the IFailureMechanism interface and several surfaceline designers through their ISurfacelineDesigner interface.
\subsubsection*{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.
\subsubsection*{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}
\subsubsection*{Geometry creator}
This submodule combines a surfaceline with a subsoil scenario. 
The output is a geometry that can be used by the failure mechanisms to perform a calculation.
\subsubsection*{Waternet creator}
A waternet describes the waterpressures in the dike embankment. 
The waterpressures are a result of the load on the system (outer waterlevel and polderlevel).
This submodule determines the waternet that will be used by the failure mechanism kernels. 
At first only the current DAM implementation will be used as a waternet creator. 
Later on new implementations can be made and applied. 
E.g.\ specific for each failure mechanism, or an implementation based on a numerical model like DgFlow.
\subsubsection{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{Programming Interface}  \label{chapterProgrammingInterface}
This is the definition of the programming interface. 
The only way to communicate to the \ProgramName is through this interface.
In the assembly Deltares.DamEngine.Interface.dll a class hass been defined: \texttt{Interface}, which provides the properties and methods which can be used to interact with the \ProgramName.

\section{Initialization}
\label{sec:Initializion}

\texttt{
\newline
        /// <summary> \newline
        /// Initializes a new instance of the <see cref="Interface"/> class. \newline
        /// </summary> \newline
        /// <param name="modelInput">The model input.</param> \newline
        public Interface(string modelInput) \newline
				}
\newline
The class has to be instantiated with an (XML) string which adheres to the XSD definition of the inputfile for the \ProgramName (See \autoref{app:DamInput.XSD}).

\section{Validation}
\label{sec:Validation}
\texttt{
\newline
        /// <summary> \newline
        /// Validates the model. \newline
        /// </summary> \newline
        /// <returns>Validation messages in an XML string</returns> \newline
        public string Validate() \newline
				}
\newline
This will validate the model and returns the messages in an XML string which adheres to the XSD definition of a message list (See \autoref{app:MessageList.XSD}).
\section{Calculation}
\label{sec:Calculation}
\texttt{
\newline
        /// <summary> \newline
        /// Performs the calculation. \newline
        /// </summary> \newline
        /// <returns>Errors and warnings in an XML string</returns> \newline
        public string Run() \newline
				}
\newline
This will perform the calculation of the model and returns an XML string which adheres to the XSD definition of the output of the \ProgramName (See \autoref{app:DamOutput.XSD}).
\section{Interaction}
\label{sec:Interaction}

The \ProgramName interacts with the calling application through delegates. The following delegates are used by the \ProgramName: \newline
\texttt{  
\newline   
		/// <summary> \newline
    /// Sends the current progress status  \newline
    /// </summary> \newline
    /// <param name="progress">The progress; this is a number between 0 and 1.</param> \newline
    public delegate void ProgressDelegate(double progress); \newline
 \newline
    /// <summary> \newline
    /// Sends  log message \newline 
    /// </summary> \newline
    /// <param name="logMessage">The log message.</param> \newline
    public delegate void SendMessageDelegate(LogMessage logMessage); \newline
\newline
    /// <summary> \newline
    /// Check if a user abort is requested \newline
    /// </summary> \newline
    /// <returns>true if user requested an abort; else false</returns> \newline
    public delegate bool UserAbortDelegate(); \newline
}
\newline
These delegates can be assigned to the properties of Interface: \newline
\texttt{
        public ProgressDelegate ProgressDelegate \newline
        public SendMessageDelegate SendMessageDelegate \newline
        public UserAbortDelegate UserAbortDelegate \newline
}
%------------------------------------------------------------------------------
\chapter{Literature}  \label{chapterLiterature}

\bibliography{../DAM_references/dam_references}



\appendix
%----------------------------------------
\chapter{DamInput} \label{app:DamInput.XSD}
These are the XSD's that apply to the input XML of the \ProgramName.

\section{DamInput.xsd}
\label{sec:DamInputXsd}

\begin{lstlisting}
<?xml version="1.0" encoding="utf-8"?>
<!-- Created with Liquid XML Studio 1.0.8.0 (http://www.liquid-technologies.com) -->
<xs:schema elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:include schemaLocation=".\DamLocation.xsd" />
  <xs:complexType name="Input">
    <xs:sequence>
      <xs:element name="Locations">
        <xs:complexType>
          <xs:sequence>
            <xs:element minOccurs="0" maxOccurs="unbounded" name="Location" type="Location" />
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
    <xs:attribute name="DamProjectType" use="required">
      <xs:simpleType>
        <xs:restriction base="xs:string">
          <xs:enumeration value="Assessment" />
          <xs:enumeration value="AssessmentRegional" />
          <xs:enumeration value="Operational" />
          <xs:enumeration value="Design" />
          <xs:enumeration value="NWO" />
        </xs:restriction>
      </xs:simpleType>
    </xs:attribute>
  </xs:complexType>
  <xs:element name="Input" />
</xs:schema>
\end{lstlisting}

\section{DamLocation.xsd}
\label{sec:DamLocationXsd}

\begin{lstlisting}
<?xml version="1.0" encoding="utf-8"?>
<!-- Created with Liquid XML Studio 1.0.8.0 (http://www.liquid-technologies.com) -->
<xs:schema elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:complexType name="Location">
    <xs:sequence>
      <xs:element name="AssesmentRegionalOptions">
        <xs:complexType>
          <xs:attribute default="Clay" name="DikeMaterialType">
            <xs:simpleType>
              <xs:restriction base="xs:string">
                <xs:enumeration value="Sand" />
                <xs:enumeration value="Peat" />
                <xs:enumeration value="Loam" />
                <xs:enumeration value="Clay" />
                <xs:enumeration value="Gravel" />
              </xs:restriction>
            </xs:simpleType>
          </xs:attribute>
          <xs:attribute name="DredgingDepth" type="xs:double" />
          <xs:attribute default="0.95" name="DetrimentFactor" type="xs:double" />
          <xs:attribute name="DikeTableHeight" type="xs:double" />
        </xs:complexType>
      </xs:element>
      <xs:element name="AssesmentOptions" />
      <xs:element name="OperationalOptions" />
      <xs:element name="DesignOptions" />
      <xs:element name="NWOOptions" />
      <xs:element name="WaternetOptions">
        <xs:complexType>
          <xs:attribute name="PhreaticLineCreationMethod" use="required">
            <xs:simpleType>
              <xs:restriction base="xs:string">
                <xs:enumeration value="ExpertKnowledgeRRD" />
                <xs:enumeration value="ExpertKnowledgeLinearInDike" />
                <xs:enumeration value="GaugesWithFallbackToExpertKnowledgeRRD" />
                <xs:enumeration value="Sensors" />
                <xs:enumeration value="None" />
              </xs:restriction>
            </xs:simpleType>
          </xs:attribute>
          <xs:attribute name="PolderLevel" type="xs:double" use="required" />
          <xs:attribute name="HeadPl2" type="xs:double" use="optional" />
          <xs:attribute name="HeadPl3" type="xs:double" use="optional" />
          <xs:attribute name="HeadPl4" type="xs:double" use="optional" />
          <xs:attribute name="DampingFactorPL3" type="xs:double" use="required" />
          <xs:attribute name="DampingFactorPL4" type="xs:double" use="required" />
          <xs:attribute name="PenetrationLength" type="xs:double" use="required" />
          <xs:attribute name="SlopeDampingFactor" type="xs:double" use="required" />
          <xs:attribute name="Pl1BelowCrestRiverside" type="xs:double" use="required" />
          <xs:attribute name="Pl1BelowCrestPolderside" type="xs:double" use="required" />
          <xs:attribute name="Pl1BelowShoulderCrestPolderside" type="xs:double" use="required" />
          <xs:attribute name="Pl1BelowToeDikePolderside" type="xs:double" use="required" />
          <xs:attribute name="Pl1BelowCrestMiddle" type="xs:double" use="optional" />
          <xs:attribute name="Pl1FactorBelowShoulderCrest" type="xs:double" use="optional" />
          <xs:attribute name="DryPl1BelowCrestMiddle" type="xs:double" use="optional" />
          <xs:attribute name="DryPl1FactorBelowShoulderCrest" type="xs:double" use="optional" />
          <xs:attribute name="IntrusionVerticalWaterPressure" use="required">
            <xs:simpleType>
              <xs:restriction base="xs:string">
                <xs:enumeration value="Standard" />
                <xs:enumeration value="Linear" />
                <xs:enumeration value="FullHydroStatic" />
                <xs:enumeration value="HydroStatic" />
                <xs:enumeration value="SemiTimeDependent" />
              </xs:restriction>
            </xs:simpleType>
          </xs:attribute>
        </xs:complexType>
      </xs:element>
      <xs:element name="General">
        <xs:complexType>
          <xs:attribute default="Primary" name="DamType">
            <xs:simpleType>
              <xs:restriction base="xs:string">
                <xs:enumeration value="Primary" />
                <xs:enumeration value="Regional" />
              </xs:restriction>
            </xs:simpleType>
          </xs:attribute>
          <xs:attribute name="Description" type="xs:string" />
          <xs:attribute name="DikeEmbankmentMaterial" type="xs:string" />
          <xs:attribute default="1.0" name="ForbiddenZoneFactor" type="xs:double" />
          <xs:attribute name="IsUseOriginalPLLineAssignments" type="xs:boolean" />
          <xs:attribute name="HeadPL2" type="xs:double" use="optional" />
          <xs:attribute name="HeadPL3" type="xs:double" use="optional" />
          <xs:attribute name="headPL4" type="xs:double" use="optional" />
        </xs:complexType>
      </xs:element>
      <xs:element name="PipingProbabilisticParameters">
        <xs:complexType>
          <xs:attribute default="Deterministic" name="LayerHeightDistribution">
            <xs:simpleType>
              <xs:restriction base="xs:string">
                <xs:enumeration value="Deterministic" />
                <xs:enumeration value="Uniform" />
                <xs:enumeration value="Triangular" />
                <xs:enumeration value="Normal" />
                <xs:enumeration value="LogNormal" />
                <xs:enumeration value="Exponential" />
                <xs:enumeration value="Gamma" />
                <xs:enumeration value="Beta" />
                <xs:enumeration value="Frechet" />
                <xs:enumeration value="Weibull" />
                <xs:enumeration value="Gumbel" />
                <xs:enumeration value="Rayleigh" />
                <xs:enumeration value="Pareto" />
                <xs:enumeration value="TruncatedNormal" />
                <xs:enumeration value="Table" />
                <xs:enumeration value="StudentT" />
              </xs:restriction>
            </xs:simpleType>
          </xs:attribute>
          <xs:attribute name="LayerHeightDeviation" type="xs:double" />
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>
</xs:schema>\end{lstlisting}

%----------------------------------------
\chapter{MessageList} \label{app:MessageList.XSD}
\begin{lstlisting}
\end{lstlisting}

%----------------------------------------
\chapter{DamOutput} \label{app:DamOutput.XSD}

\section{DamOutput.xsd}
\label{sec:DamOutputXsd}
\begin{lstlisting}
\end{lstlisting}

\pagestyle{empty}
\mbox{}

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