\documentclass[signature]{deltares_report}
\usepackage{listings}
\usepackage[titletoc]{appendix}
%-----------------------------------------------
\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}
\newcommand{\WbiKernel}{WBI macrostability kernel\xspace}
\newcommand{\DGeostability}{D-Geo Stability 18.1 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.4}

\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.5}
\datei{Nov 2018}
\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.

\subsection{Revision 0.4}
\label{sec:Revision04}
\begin{itemize}
	\item Updated the interface description of the failure mechanism wrapper.
	\item Added a chapter on adding a new Failure Mechanism.
\end{itemize}

\subsection{Revision 0.5}
\label{sec:Revision05}
\begin{itemize}
	\item Added a chapter on Failure Mechanism implementations.
	\item Added description of the implementation of the WBI Macrostability kernel.
\end{itemize}

%------------------------------------------------------------------------------
\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 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 is not yet to be implemetend in \ProgramName and therefore 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}
These are the main design principals to maintain during the \ProgramName development.
\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 no 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 4 forces  (not opensource).
	\item D-Geo Stability inward (not opensource, but commercial).
	\item D-Geo Stability outward (not opensource, but commercial).
	\item D-Geo Horizontal Balance (not opensource, but commercial).
\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}
The following main failure mechanisms are implemented.
\begin{itemize}
	\item Macrostability inward.
	\item Macrostability outward.
	\item Piping.
	\item Horizontal Balance.
\end{itemize}

\section{Scenarios} \label{sec:Scenarios}
The verb Scenarios is widely (ab)used 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}
The following Dam project types are supported
\begin{itemize}
	\item Assessment
	\item Operational
	\item Design
	\item NWO (not yet implemented)
\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}
\label{sec:FailureMechanismWrapperInterface}
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}

Next to that, each wrapper can have properties that hold data that are specific to the failure mechanism.\newline
Example:
D-Geostability needs parameters specifying the grid, tangent lines et. These can be passed as properties to the wrapper directly.\newline

\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. The kernel input will be based on the general dam kernel input, the possible addiotional kernel properties and when required calculations in order to determine certain input. Furthermore it initializes the kernel data output (IKernelDataOutput). \newline				
\texttt{
        /// <summary> \newline
        /// Prepares the failure mechanism input based on general dam kernel input and failure mechanism specific properties. \newline
        /// </summary> \newline
        /// <param name="damKernelInput">The general dam kernel input.</param> \newline
        /// <param name="iterationIndex">The number of the current iteration</param> \newline
        /// <param name="kernelDataInput">The kernel data input.</param> \newline
        /// <param name="kernelDataOutput">The kernel data output.</param> \newline
        /// <returns> \newline
        /// Result of the prepare \newline
        /// </returns>   \newline
				PrepareResult Prepare(DamKernelInput damKernelInput, int iterationIndex, out IKernelDataInput damKernelInput, out IKernelDataOutput kernelDataOutput); \newline
				}
\newline				
This method returns:
\newline				
\texttt{
    public enum PrepareResult \newline
    \{ \newline
        Successful,   \newline
        Failed, \newline
        NotRelevant \newline
    \}; \newline
		}
\newline	
The method has the following parameters:			
\begin{itemize}
	\item \texttt{DamKernelInput damKernelInput}: the main input data object; it contains data from the \ProgramName.
	\item \texttt{IKernelDataInput damKernelInput}: in this object the data is filled that is needed by the specific \kernel; it will be passed to the \kernel as input; each \kernel wrapper will have its own implementation of IKernelDataInput.
	\item \texttt{IKernelDataOutput kernelDataOutput}: in this object all the output of the \kernel is stored; it is also used for intermediate results; each \kernel wrapper will have its own implementation of IKernelDataOutput.
\end{itemize}

\subsubsection{Validate}
\label{sec:Validate}
\texttt{        /// <summary> \newline
        /// Validates the kernel data input. \newline
        /// </summary> \newline
        /// <param name="kernelDataInput">The kernel data input.</param> \newline
        /// <param name="kernelDataOutput">The kernel data output.</param> \newline
        /// <param name="messages">The messages.</param> \newline
        /// <returns> \newline
        /// Number of errors that prevent a calculation \newline
        /// </returns> \newline
        int Validate(IKernelDataInput kernelDataInput, IKernelDataOutput kernelDataOutput, out List<LogMessage> messages); \newline}
The purpose of this method is to validate the data that will be used as input for the failure mechanism.\newline
It returns an integer:\newline
0: no errors. A calculation is possible. It is possible that there are warning messages. \newline
> 0: number of error messages that prevent a calculation. In this case, the calculation result (as part of the IKernelDataOutput) will be set to reflect this.\newline
This method has the following parameters:
\begin{itemize}
	\item \texttt{IKernelDataInput kernelDataInput}: kernel input data.
	\item \texttt{IKernelDataOutput kernelDataOutput}: kernel output data.
	\item \texttt{List<LogMessage> messages}: a list of messages produced by the validation
\end{itemize}

\subsubsection{Execute}
\label{sec:Execute}
\texttt{        /// <summary> \newline
        /// Performs a failure mechanism calculation based on the input. \newline
        /// </summary> \newline
        /// <param name="kernelDataInput">The kernel data input.</param> \newline
        /// <param name="kernelDataOutput">The kernel data output.</param> \newline
        /// <param name="messages">The messages.</param> \newline
        void Execute(IKernelDataInput kernelDataInput, IKernelDataOutput kernelDataOutput, out List<LogMessage> messages); \newline
}
This method performs the actual calculation of the failure mechanism.  \newline
This method has the following parameters:
\begin{itemize}
	\item \texttt{IKernelDataInput kernelDataInput}: kernel input data.
	\item \texttt{IKernelDataOutput kernelDataOutput}: kernel output data.
	\item \texttt{List<LogMessage> messages}: a list of messages produced by the validation
\end{itemize}
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 the following parameters:
\begin{itemize}
	\item \texttt{IKernelDataInput kernelDataInput}: kernel input data.
	\item \texttt{IKernelDataDesignInput kernelDataInput}: design input.
	\item \texttt{IKernelDataOutput kernelDataOutput}: kernel output data.
	\item \texttt{IKernelDataDesignOutput kernelDataOutput}: design output; it 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.).
	\item \texttt{List<LogMessage> messages}: a list of messages produced by the design.
\end{itemize}
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}
\texttt{        /// <summary> \newline
        /// Fills the dam result based on the kernel output. \newline
        /// </summary> \newline
        /// <param name="damKernelInput">The dam kernel input.</param> \newline
        /// <param name="kernelDataOutput">The kernel data output.</param> \newline
        /// <param name="resultMessage">The result message.</param> \newline
        /// <param name="designResults">The design results.</param> \newline
        void PostProcess(DamKernelInput damKernelInput, IKernelDataOutput kernelDataOutput, string resultMessage, out List<DesignResult> designResults); \newline
}This method has the following parameters
\begin{itemize}
	\item \texttt{DamKernelInput damKernelInput}: the main dam input data object; it contains data from the \ProgramName.
	\item \texttt{IKernelDataOutput kernelDataOutput}: kernel output data.
	\item \texttt{string resultMessage}: this describes the result of the calculation.
	\item \texttt{DesignResult designResult}: the main dam output data object. 
\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">Xml string containing the model input.</param> \newline
        public EngineInterface(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}).

\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:Messages}).
\section{Calculation}
\label{sec:Calculation}
\texttt{
\newline
        /// <summary> \newline
        /// Performs the calculation. \newline
        /// </summary> \newline
        /// <returns>The output of the calculation 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}).
\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{XML Serialization}  \label{chapterXmlSerialization}

\section{Generating serialization code}
\label{sec:GeneratingSerializationCode}

For the XML serialization a Visual Studio Tool is used. This tool XSD.exe creates objects based on XML schema definitions (*.xsd). To use this tool the following steps should be taken:
\begin{itemize}
	\item Start the Developer Command Prompt (for VS2015) and go to the folder containing the XSD's.
	\item Create the classes by running the batchfile "GenerateClasses.bat". This generates 2 source files containing the generated objects  (DamInput.cs and DamOutput.cs).
	\item The 2 source files are then copied to the correct locations in the source tree, so they can be compiled.
\end{itemize}
The batchfile contains the following lines: \newline
\texttt{REM Start the Developer Command Prompt (for VS2015) and go to this directory. Then start this batchfile.}\newline
\texttt{xsd /c /l:cs /n:Deltares.DamEngine.Io.XmlInput DamInput.xsd}\newline
\texttt{copy DamInput.cs ..\textbackslash src\textbackslash Deltares.DamEngine.Io\textbackslash DamInput.cs}\newline
\texttt{xsd /c /l:cs /n:Deltares.DamEngine.Io.XmlOutput DamOutput.xsd}\newline
\texttt{copy DamOutput.cs ..\textbackslash src\textbackslash Deltares.DamEngine.Io\textbackslash DamOutput.cs}\newline
\newline
The classes in the generated source files can be serialized into XML strings using the .NET library class XmlSerializer, which is part of the System.Xml.Serialization assembly. \newline
The following classes are used for transferring the Dam Engine data model into the serializer objects and back:
\begin{itemize}
	\item FillDamFromXmlInput
	\item FillXmlInputFromDam
	\item FillDamFromXmlOutput
	\item FillXmlOutputFromDam
\end{itemize}

\section{Changing the XSD definition}
\label{sec:ChangingTheXsdDefinition}

When the interface has to be changed because parameters are added, changed or removed you can do that as follows:
\begin{itemize}
	\item Change the XSD.
	\item Regenerate the serializer objects.
	\item Adapt the transfer objects.
\end{itemize}
\emph{Note: DO NOT manually change the code of the generated objects DamInput.cs and DamOutput.cs, because the changes will be lost when these files are regenerated!}

%------------------------------------------------------------------------------
\chapter{Adding a Failure Mechanism}  \label{chapterAddingFailureMechanism}
Adding a new failure mechanism to \ProgramName is something that should be releative easy to do. The architecture of \ProgramName has been setup in a way that all failure mechanism specific code is put as much as possible in 1 place.

When a new failure mechanism is to be implemented, several steps have to be taken. 
\begin{itemize}
	\item Add Failure Mechanism Wrapper (this is the main place for all failure mechanism specific code).
	\item Create an Instance of a Failure Mechanism Wrapper.
	\item Add Failure Mechanism Specific Data to Data Model.
	\item Add Failure Mechanism Specific Data to XML Input.
	\item Add Failure Mechanism Specific Data to XML Output.
\end{itemize}

In the following sections the steps are illustrated with the piping Bligh Failure mechanism.

\section{Add Failure Mechanism Wrapper}
\label{sec:AddFailureMechanismWrapper}
Create a Failure Mechanism Wrapper that conforms to the Failure Mechanism Wrapper interface as described in \autoref{sec:FailureMechanismWrapperInterface}. The implementation of the wrapper for Piping Bligh can be found in the class \newline
Deltares.DamEngine.Calculators.KernelWrappers.DamPipingBligh.

\section{Create an Instance of the Failure Mechanism Wrapper}
\label{sec:CreateInstanceFailureMechanismWrapper}
To be able to use the Failure Mechanism wrapper an instance has to be instantiated. For all failure mechanisms this is done in \newline Deltares.DamEngine.Calculators.KernelWrappers.Common.KernelWrapperHelper.CreateKernelWrapper().

\section{Add Failure Mechanism Specific Data to Data Model}
\label{sec:AddFailureMechanismSpecificDataToDataModel}
This is only needed if the data that is already implemented in the \ProgramName is not enough to meet the necessary input data for the failure mechanism kernel. Or if more result data has to be added to accommodate the passing of the failure mechanism output. For piping Bligh e.g. the Soil parameter Soil.PermeabKx has been added (among other parameters) as input. As output the output class PipingDesignResults has been added.

\section{Add Failure Mechanism Specific Data to XML Input}
\label{sec:AddFailureMechanismSpecificDataToXmlInput}
This is only needed when the data model has been changed (see \autoref{sec:AddFailureMechanismSpecificDataToDataModel}) to accommodate more input properties. To change the input XML definition, the DamInput.xsd definition or one of its dependent xsd's has to be adapted (see \autoref{app:DamInput}). Also the reader and writer routines have to be adapted. This can be done in the class \newline 
Deltares.DamEngine.Interface.FillDamFromXmlInput.

\section{Add Failure Mechanism Specific Data to XML Output}
\label{sec:AddFailureMechanismSpecificDataToXmlOutput}
This is only needed when the data model has been changed (see \autoref{sec:AddFailureMechanismSpecificDataToDataModel}) to accommodate more output properties. To change the output XML definition, the DamOuput.xsd definition or one of its dependent xsd's has to be adapted (see \autoref{app:DamOutput}). Also the reader and writer routines have to be adapted. This can be done in the class \newline 
Deltares.DamEngine.Interface.FillXmlOutputFromDam.
%------------------------------------------------------------------------------
\chapter{Failure Mechanism Implementations}
\label{sec:FailureMechanismImplementations}

\section{Piping Bligh}
\label{sec:PipingBligh}
TODO...

\section{Piping Sellmeijer 4 Forces}
\label{sec:PipingSellmeijer4Forces}
TODO...

\section{Piping Sellmeijer VNK}
\label{sec:PipingSellmeijerVNK}
TODO...

\section{WBI Piping Sellmeijer Revised}
\label{sec:WBIPipingSellmeijerRevised}
TODO...

\section{Macrostability Inwards}
\label{sec:MacrostabilityInwards}
TODO...

\section{Macrostability Outwards}
\label{sec:MacrostabilityOutwards}
TODO...

\section{Macrostability Horizontal Balance}
\label{sec:MacrostabilityHorizontalBalance}
TODO...

\section{WBI Macrostability Inwards}
\label{sec:WbiMacrostabilityInwards}
For WBI a new macrostability kernel has been build. A Functional Design  \citep{Zwan2017a} and a Technical Design \citep{MacroStabilityKernel_TechnicalDesign} is available. Currently this kernel only supports macrostability inwards for the model Uplift Van.
The API of this kernel is based on an XML file that contains all the necessary data for the input of the kernel. The XML is defined with a set of XML schema's (XSD's). These XSD's can be found in chapter 2.3 of the Technical Design \citep{MacroStabilityKernel_TechnicalDesign}.

\subsection{Initial implementation}
\label{sec:InitialImplementation}
The first implementation of the \WbiKernel will not be a full implementation. It will implement the same options that were implemented in the original Macrostability Inwards implementation (which uses the \DGeostability).\newline
Therefore the following input options (see \autoref{sec:MappingDamEngineDataWbiMacrostability}) will not be implemented:
\begin{itemize}
	\item PreconsolidationStresses 
	\item ConsolidationValues
	\item MultiplicationFactorsCPhiForUplift
	\item SpencerSlipPlanes
    \item SlipPlaneConstraints
    \item GeneticAlgorithmOptions
    \item LevenbergMarquardtOptions
	\item Waternet creation options (defined in Location)
\end{itemize}
Furthermore, no Waternet Daily will be specified. This was introduced in the \WbiKernel when POP is requested.
Also in the first implementation the waternet will be created by the \ProgramName. The waternet creator of the \WbiKernel will not be used. So the parameters used for the waternet creation do not have to be filled in when calling the \WbiKernel. Those are the parameters defined in \autoref{table-MappingDamEngineLocationWbiMacrostability}.

\subsection{Mapping of the \ProgramName data}
\label{sec:MappingDamEngineDataWbiMacrostability}
The \WbiKernel has to be filled with input, that can be obtained from the \ProgramName data. In the following tables a mapping of the needed data to the \ProgramName data is defined. The data is contained in the classes DamKernelInput and DamMacroStabilityInput.
\begin{table}[H]
	\small
	\begin{tabular}{|p{60mm}|p{\textwidth-60mm-24pt}|} \hline
		\textbf{WBI Macrostability} StabilityModel  & \textbf{\ProgramName} DamInput.xsd \\ \hline
		MoveGrid & Fixed value: TRUE (default)  \\ \hline
		MaximumSliceWidth & Fixed value: 1.0 (default) \\ \hline
		SearchAlgorithm & DamMacroStabilityInput -> FailureMechanismParametersMStab -> MStabParameters -> SearchMethod \\ \hline
		ModelOption & DamMacroStabilityInput -> FailureMechanismParametersMStab -> MStabParameters -> Model \\ \hline
		Orientation & DamMacroStabilityInput -> FailureMechanismParametersMStab -> MStabParameters -> GridPosition \\ \hline
		\hline
		SoilModel -> Soils & DamKernelInput -> Location -> SoilList (See \autoref{table-MappingDamEngineSoilsWbiMacrostability})\\ \hline
		SoilProfile & DamKernelInput -> SubSoilScenario -> SoilProfile2D \\ \hline
		SurfaceLine & DamKernelInput -> Location -> SurfaceLine \\ \hline
		Location & DamKernelInput -> Location (See \autoref{table-MappingDamEngineLocationWbiMacrostability})\\ \hline
		PreconsolidationStresses & DO-NOT-IMPLEMENT \\ \hline
		UniformLoads & generated (based on Location -> StabilityOptions -> Trafficload) \\ \hline
		ConsolidationValues & DO-NOT-IMPLEMENT \\ \hline
		MultiplicationFactorsCPhiForUplift & DO-NOT-IMPLEMENT \\ \hline
		Waternets & generated  \\ \hline
		SpencerSlipPlanes & DO-NOT-IMPLEMENT \\ \hline
		UpliftVanCalculationGrid & generated \\ \hline
		SlipPlaneConstraints & DO-NOT-IMPLEMENT (See \autoref{table-MappingDamEngineSlipPlaneConstraintsWbiMacrostability}) \\ \hline
		GeneticAlgorithmOptions & DO-NOT-IMPLEMENT \\ \hline
		LevenbergMarquardtOptions & DO-NOT-IMPLEMENT \\ \hline
\end{tabular}
	\caption{\small Mapping of the \WbiKernel data to the \ProgramName.}
	\label{table-MappingDamEngineDataWbiMacrostability}
\end{table}
\begin{table}[H]
	\small
	\begin{tabular}{|p{70mm}|p{\textwidth-70mm-24pt}|} \hline
		\textbf{WBI Macrostability} Soil  & \textbf{\ProgramName} Soil \\ \hline
		AbovePhreaticLevel & AbovePhreaticLevel \\ \hline
		BelowPhreaticLevel & BelowPhreaticLevel \\ \hline
		DilatancyType & DilatancyType \\ \hline
		Cohesion & Cohesion \\ \hline
		FrictionAngle & FrictionAngle \\ \hline
		RatioCuPc & RatioCuPc \\ \hline
		StrengthIncreaseExponent & StrengthIncreaseExponent  \\ \hline
		OCR & OCR \\ \hline
		ShearStrengthModel & ShearStrengthModel \\ \hline
	\end{tabular}
	\caption{\small Mapping of the \WbiKernel Soils to the \ProgramName Soils.}
	\label{table-MappingDamEngineSoilsWbiMacrostability}
\end{table}
The parameters defined in the following table for Location are all parameters that are used by the waternet creator of the \WbiKernel. They will not yet be implemented (as explained above).
\begin{table}[H]
	\small
	\begin{tabular}{|p{65mm}|p{\textwidth-65mm-24pt}|} \hline
		\textbf{WBI Macrostability} Location  & \textbf{\ProgramName} Location \\ \hline
		DikeSoilScenario & TO-BE-ADDED \\ \hline
		WaterLevelRiver & Scenario -> RiverLevel \\ \hline
		WaterLevelRiverAverage & TO-BE-ADDED \\ \hline
		WaterLevelRiverLow & Scenario -> RiverLevelLow \\ \hline
		WaterLevelPolder & PolderLevel \\ \hline
		DrainageConstructionPresent & TO-BE-ADDED \\ \hline
		XCoordMiddleDrainageConstruction & TO-BE-ADDED \\ \hline
		ZCoordMiddleDrainageConstruction & TO-BE-ADDED \\ \hline
		MinimumLevelPhreaticLineAtDikeTopRiver & TO-BE-ADDED \\ \hline
		MinimumLevelPhreaticLineAtDikeTopRiver & TO-BE-ADDED \\ \hline
		UseDefaultOffsets & TO-BE-ADDED \\ \hline
		PlLineOffsetBelowPointBRingtoetsWti2017 & TO-BE-ADDED \\ \hline
		PlLineOffsetBelowDikeTopAtPolder & Scenario -> PlLineOffsetBelowDikeTopAtPolder \\ \hline
		PlLineOffsetBelowShoulderBaseInside & Scenario -> PlLineOffsetBelowShoulderBaseInside \\ \hline
		PlLineOffsetBelowDikeToeAtPolder & Scenario -> PlLineOffsetBelowShoulderBaseInside \\ \hline
		HeadInPLLine2Inwards & HeadPl2 \\ \hline
		HeadInPLLine3 & Scenario -> HeadPl3 \\ \hline
		HeadInPLLine4 & Scenario -> HeadPl4 \\ \hline
		AdjustPl3And4ForUplift & set to TRUE \\ \hline
		PenetrationLength & ModelParametersForPlLines -> PenetrationLength \\ \hline
		LeakageLengthOutwardsPl3 & DO-NOT-IMPLEMENT \\ \hline
		LeakageLengthInwardsPl3 & generate based on ModelParametersForPlLines -> DampingFactorPl3 \\ \hline
		LeakageLengthOutwardsPl4 & DO-NOT-IMPLEMENT \\ \hline
		LeakageLengthInwardsPl4 & generate based on ModelParametersForPlLines -> DampingFactorPl4 \\ \hline
	\end{tabular}
	\caption{\small Mapping of the \WbiKernel Slip Plane Location to the \ProgramName Location.}
	\label{table-MappingDamEngineLocationWbiMacrostability}
\end{table}
The parameters defined in the following table for Constraints will not yet be implemented (as explained above).
\begin{table}[H]
	\small
	\begin{tabular}{|p{70mm}|p{\textwidth-70mm-24pt}|} \hline
		\textbf{WBI Macrostability} Constraints  & \textbf{\ProgramName} Constraints \\ \hline
		SlipPlaneMinDepth & Location -> StabiltiyOptions -> MinimumCircleDepth  \\ \hline
		SlipPlaneMinLength &  TO-BE-ADDED \\ \hline
		CreateZones & TO-BE-ADDED \\ \hline
		AutomaticForbiddenZones & TO-BE-ADDED \\ \hline
		XEntryMin & TO-BE-ADDED \\ \hline
		XEntryMax & TO-BE-ADDED \\ \hline
		MaxAllowedAngleBetweenSlices & TO-BE-ADDED \\ \hline
		RequiredForcePointsInSlices & TO-BE-ADDED \\ \hline
	\end{tabular}
	\caption{\small Mapping of the \WbiKernel Slip Plane Constraints to the \ProgramName  data.}
	\label{table-MappingDamEngineSlipPlaneConstraintsWbiMacrostability}
\end{table}

\subsubsection{Mapping of pl lines to waternet}
\label{sec:MappingPlLinesToWaternet}

Dam Engine has a set of pl lines: Pl 1, Pl 2, Pl 3, Pl 4. Pl 1 is the phreatic line and it always exists. The other pl lines are optional. The pl lines from the Dam Engine are converted to a waternet that can be used in WBI Macrostability.

The waternet consists of a phreatic line, a list of head lines and a list of waternet lines. Each waternet line can have an associated head line.
To create the waternet lines the soil profile data is used to determine the 'bottom aquifer' (the lowest set of one or more connected aquifer layers) and the 'in-between aquifer' (the first aquifer (layer set) that lies above the bottom aquifer).

Pl 1 becomes the phreatic line. \\
If Pl 2 exists it becomes a head line. If there is at least one aquifer, a waternet line is created along the top of the bottom aquifer + penetration length. \\
If Pl 3 exists it becomes a head line. If there are at least two aquifers, a waternet line is created along the top of the in-between aquifer. \\
If Pl 4 exists it becomes a head line. If there is at least one aquifer, a waternet line is created along the top of the bottom aquifer. \\

\subsection{Mapping of the validation result}
\label{sec:MappingValidationResultWbiMacrostability}
The \WbiKernel returns the validation result when the Validate function is called. In the following table a mapping of the validation result to the \ProgramName data is defined.
\begin{table}[H]
	\small
	\begin{tabular}{|p{60mm}|p{\textwidth-60mm-24pt}|} \hline
		\textbf{WBI Macrostability} WTIStabilityModelValidation.xsd  & \textbf{\ProgramName} DamDesignResult.xsd -> StabilityDesignResults \\ \hline
		Validations -> ValidationsType & ResultMessage -> LogMessageType\\ \hline
\end{tabular}
	\caption{\small Mapping of the \WbiKernel validation result to the \ProgramName.}
	\label{table-MappingValidationResultWbiMacrostability}
\end{table}
When the Validations part is empty it means that the input is Valid. When there are one or more validations, they are added to the messages of the design results. The type of message can be Info, Warning or Error. The validation fails when there is at least one Error message.

\subsection{Mapping of the calculation result}
\label{sec:MappingCalculationResultWbiMacrostability}
The \WbiKernel returns the calculation result when the Run function is called. In the following table a mapping of the calculation result to the \ProgramName data is defined. For now, only the parts that we currently use are described.
\begin{table}[H]
	\small
	\begin{tabular}{|p{60mm}|p{\textwidth-60mm-24pt}|} \hline
		\textbf{WBI Macrostability} WTIStabilityModelResult.xsd -> WTIStabilityModelResult  & \textbf{\ProgramName} DamDesignResult.xsd -> StabilityDesignResults \\ \hline
		Calculated & CalculationResult\\ \hline
		SafetyFactor & SafetyFactor\\ \hline
		Messages & ResultMessage\\ \hline
		MinimumSafetyCurve -> first Slice, TopLeftPoint X & CircleSurfacePointLeftXCoordinate\\ \hline
		MinimumSafetyCurve -> last Slice, TopRightPoint X & CircleSurfacePointRightXCoordinate\\ \hline
		ModelOption & StabilityModelType\\ \hline
\end{tabular}
	\caption{\small Mapping of the \WbiKernel validation result to the \ProgramName.}
	\label{table-MappingCalculationResultWbiMacrostability}
\end{table}
Calculated is a boolean. When Calculated is true the CalculationResult is Succeeded, otherwise RunFailed.
The type of message can be Info, Warning or Error.
Presumed is that when Calculated is true, there are no error messages.


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

\bibliography{../DAM_references/dam_references}

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

\section{DamInput.xsd}
\label{sec:DamInputXsd}
This is the DamInput XSD.
\lstinputlisting{xsd/DamInput.xsd}

\section{DamLocation.xsd}
\label{sec:DamLocationXsd}
This is the Location XSD.
\lstinputlisting{xsd/DamLocation.xsd}

\section{DamSurfaceLine.xsd}
\label{sec:DamSurfaceLine}
This is the DamSurfaceLine XSD.
\lstinputlisting{xsd/DamSurfaceLine.xsd}

\section{DamSoil.xsd}
\label{sec:DamSoil}
This is the DamSoil XSD.
\lstinputlisting{xsd/DamSoil.xsd}

\section{DamSegment.xsd}
\label{sec:DamSegment}
This is the DamSegment XSD.
\lstinputlisting{xsd/DamSegment.xsd}

\section{DamSoilProfile1D.xsd}
\label{sec:DamSoilProfile1D}
This is the Dam SoilProfile XSD.
\lstinputlisting{xsd/DamSoilProfile1D.xsd}

\section{DamSoilProfile2D.xsd}
\label{sec:DamSoilProfile2D}
This is the DamSoilProfile2D XSD.
\lstinputlisting{xsd/DamSoilProfile2D.xsd}

\section{DamStabilityParameters.xsd}
\label{sec:DamStabilityParameters}
This is the DamStabilityParameters XSD.
\lstinputlisting{xsd/DamStabilityParameters.xsd}

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

\lstinputlisting{xsd/Message.xsd}

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

\section{DamOutput.xsd}
\label{sec:DamOutput}
This is the DamOutput XSD.
\lstinputlisting{xsd/DamOutput.xsd}

\section{Message.xsd}
\label{sec:Message}
This is the Message XSD.
\lstinputlisting{xsd/Message.xsd}

\section{DamCalculationResults.xsd}
\label{sec:DamCalculationResults}
This is the DamCalculationResults XSD.
\lstinputlisting{xsd/DamCalculationResults.xsd}

\pagestyle{empty}
\mbox{}

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