\documentclass{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{\MacrostabilityKernel}{Macrostability kernel\xspace}
\newcommand{\DGeostability}{D-Geo Stability 18.1 kernel\xspace}
\newcommand{\DStability}{D-Stability\xspace}
\newcommand{\StixWriter}{Stix File Writer\xspace}
\title{\ProgramName}
\subtitle{Technical Design}
\projectnumber{1210702-000}
\client{Deltares - Geo engineering DKS}
\reference{1210702-000-GEO-0004}
\classification{-}
\author{Tom The, John Bokma}
\partner{-}
\contact{tom.the@deltares.nl, john.bokma@deltares.nl}
\documentid{-}
\organisationi{Deltares}
\publisheri{Deltares - DSC}

\date{Dec. 2024}
\version{0.7}

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

\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.\newline
\newline
\textbf{\footnotesize{Samenvatting}} \newline
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}

\versioni{0.6}
\datei{July 2022}
\authori{John Bokma, Tom The}
\revieweri{Walter Austmann}
\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")
\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}
\label{sec:DocumentRevisions}

\subsection{Revision 0.7}
\label{sec:Revision07}
\todo{Adapt to new and changed features.}

\subsection{Revision 0.6}
\label{sec:Revision06}
Updated for the options of the Macrostability kernel.

\subsection{Revision 0.5}
\label{sec:Revision05}
A chapter is added on Failure Mechanism implementations. Furthermore, a description is added of the implementation of the Macrostability kernel.

\subsection{Revision 0.4}
\label{sec:Revision04}
The interface description of the failure mechanism wrapper is updated. Furthermore, a chapter is added on adding a new Failure Mechanism.

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

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

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

%------------------------------------------------------------------------------
\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}
The Dike assessment module is discontinued.

\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 implementend 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.6.1 framework. The development environment will be Visual Studio 2019.

\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 Deltares.StixFileWriter (to be able to produce .stix files)
	\item Deltares.StixFileReader (to be able to read .stix files to be able to use 2D profiles)
\end{itemize}

Other libraries may be used under the condition that they are open source and free components, that are free to redistribute. 
A second demand is that a new library must be available in a 64 bit version too.
This to enable a possible switch to a full 64 bit version of the kernel.\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: \ProgramName does no longer uses the DSL (Delta Shell Light) library.


\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 Piping Sellmeijer Revised (WBI). 
	\item Macrostability inward
	\item Macrostability outward (new).
\end{itemize}

\Note: Piping Sellmeijer VNK is a pure 32 bit program which can not be made available in 64 bit (bar a complete rewrite). 
In case a 64 bit version is required, this failure mechanism should be discontinued.

%------------------------------------------------------------------------------
\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.	
\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 2 types of scenarios:
\begin{itemize}
	\item Subsoil scenario.
	\item Design 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).

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

\subsection{Input}
\paragraph*{DamProjectType}
The following Dam project types are supported
\begin{itemize}
	\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 selected 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{Design Dikes}
This module performs an design calculation for all types of dikes.
This module offers two types of analysis, \textit{No Adaption} and \textit{Adapt Geometry}.
 
\paragraph*{Design calculation, No Adaption}
This is the main submodule of the primary design calculation. 
This submodule contains the main loop of the calculation.
The calculations are performed with the data given as is.

\paragraph*{Design calculation, Adapt Geometry}
This is the main submodule of the primary design calculation. 
This submodule contains the main loop of the calculation.
In this option, 
calculations are performed and then checked whether the required safety is met. 
If the safety requirement is met, 
the calculation for that item stops and returns its results. 
When it is not, the geometry is adapted 
(see \todo{describe geometry adaptions}) 
until the safety requirement is met or possibilty to adapt further. 

\subsection{Calamity module}
This module (also known as the Operational 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.

\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: 
\MacrostabilityKernel has the ability to calculate the failure mechanism macrostability inwards.
In this case 1 wrapper is 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:
\MacrostabilityKernel needs parameters specifying the grid, tangent lines etc. 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 \MacrostabilityKernel)
\subsubsection*{Macrostability outwards}
Calculation wrapper for Macrostability outward (future).
\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 (WBI)}
\label{sec:PipingBligh}
The WBI Piping kernel is used to support this failure mechanism.

\subsection{Mapping of the DAM Engine data}
The Bligh Calculator of the WBI Piping kernel has to be filled with input, that can be obtained from the \ProgramName data. 
In \autoref{tab:MappingDamEngineDataBlighCalculator} a mapping of the needed data to the \ProgramName data is defined.

\begin{table}[H]
	\small
	\begin{tabular}{|p{35mm}|p{\textwidth-35mm-24pt}|} \hline
		\textbf{WBI Piping} BlighCalculator.cs & \textbf{\ProgramName} DamKernelInput \\ \hline
		HRiver & RiverLevelHigh  \\ \hline
		HExit & Max(Location.CurrentScenario.PolderLevel, surfaceLevel$^{a}$) \\ \hline
		Rc & Fixed value: 0.3 \\ \hline
		DTotal & calculated using WtiPipingHelper.DetermineHeightCoverLayer, based on surfaceLevel$^{1}$ and the top level of the aquifer where uplift occurs. \\ \hline
		SeepageLength & xExit$^{b}$ - xEntry, where xEntry is the X co-ordinate of the characteristic point DikeToeAtRiver of Location.SurfaceLine \\ \hline
		D50 & 0.81 $\times$ D70 where D70 is the soil property Soil.DiameterD70 of the layer where uplift occurs.\\ \hline
		ModelFactorPiping & Fixed value: 1.0 \\ \hline		
		\multicolumn{2}{p{\textwidth-12pt}}{$^{a}$ surfaceLevel is the Z location along Location.SurfaceLine at xExit$^{b}$.} \\
		\multicolumn{2}{p{\textwidth-12pt}}{$^{b}$ xExit is the X-location where uplift occurs, calculated using UpliftLocationDeterminator.GetLocationAndResult.} \\
\end{tabular}
	\caption{Mapping of the Bligh Calculator input data of the WBI Piping kernel to the \ProgramName.}
	\label{tab:MappingDamEngineDataBlighCalculator}
\end{table}

\subsection{Mapping of the calculation result}
The Bligh Calculator of the WBI Ping kernel returns the calculation result when the Calculate function is called.
In the following table a mapping of the calculation result to the \ProgramName data is defined. 

\begin{table}[H]
	\small
	\begin{tabular}{|p{60mm}|p{\textwidth-60mm-24pt}|} \hline
		\textbf{\ProgramName} WtiPipingBlighOutput.cs & \textbf{WBI Piping} BlighCalculator.cs \\ \hline
		CalculationResult & When the calculation throws an exception the CalculationResult is UnexpectedError. 
		When no uplift occurs, the CalculationResult is NoRun, otherwise Succeeded. \\ \hline
		FoSp & FoSp \\ \hline
		Hc & Hc \\ \hline		
\end{tabular}
	\caption{Mapping of the Bligh Calculator result of the WBI Piping kernel to the \ProgramName.}
\end{table}

\section{Piping Sellmeijer Revised (WBI)}
\label{sec:WBIPipingSellmeijerRevised}
The WBI Piping kernel is used to support this failure mechanism. 
\todo{Describe mapping of WBI piping kernel}

\section{Macrostability Inwards/Outwards}
\label{sec:MacrostabilityInwards}
The macrostability kernel is used to support these failure mechanisms. 
A Functional Design  \citep{MacroStabilityReqAndFD22} and a Technical Design \citep{MacroStabilityKernel_TechnicalDesign} is available. \newline
Currently only a subset of this kernel will be supported from \ProgramName:
\begin{itemize}
	\item macrostability inwards for the model Bishop (search method Brute Force).
	\item macrostability inwards for the model Uplift Van (search methods Brute Force and BeeSwarm).
	\item macrostability inwards for combi model Bishop-Uplift Van (search method for Bishop part Brute Force;  for the Uplift Van part search methods Brute Force and BeeSwarm).
	\item macrostability outwards for the model Bishop (search method Brute Force).
\end{itemize}

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 \MacrostabilityKernel 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:MappingDamEngineDataMacrostability}) will not be implemented:
\begin{itemize}
	\item PreconsolidationStresses 
	\item MultiplicationFactorsCPhiForUplift
	\item SpencerSlipPlanes
  \item SlipPlaneConstraints
  \item GeneticAlgorithmOptions (except for BeeSwarm)
  \item LevenbergMarquardtOptions
	\item Waternet creation options (defined in Location)
\end{itemize}
Furthermore, no Waternet Daily will be specified. This was introduced in the \MacrostabilityKernel when POP is requested.
Also in the first implementation the waternet will be created by the \ProgramName. The waternet creator of the \MacrostabilityKernel will not be used. So the parameters used for the waternet creation do not have to be filled in when calling the \MacrostabilityKernel. Those are the parameters defined in \autoref{table-MappingDamEngineLocationMacrostability}.

\subsection{Data communication between \ProgramName and \MacrostabilityKernel}
\label{subsec:DataCommunicationStabilityKernel}
The data is transferred from the \ProgramName to the \MacrostabilityKernel in memory to get the best performance in terms of speed. 
However, the data is written to files using the proper calculation folder in Macro Stability kernel XML format (*.skx) too. 

The proper calculation folder is defined as : \\

\quad \textit{current project folder}\textbackslash \textit{projectname}.Calc\textbackslash \textit{failuremechanisme}\textbackslash \textit{model}\textbackslash 

where:\\
\begin{itemize}
	\item \textit{current project folder} is the folder where your project resides.
	\item \textit{projectname} is the name of your project
	\item \textit{failuremechanisme} is the used failure mechanism such as Stabilty or Piping.
	\item \textit{model} is the used model such as UpliftVan or Bligh
\end{itemize}

To be able to tell what file belongs to which calculation, the following naming convention is used:

\quad Loc(\textit{location name})Sce(\_\textit{scenario id})Pro(\_\textit{profile name}).skx

When a Design calculation is made with possible adaption of the geometry, the name will also display the iteration index when required (the very first unadapted calculation will be named as above, when adapation is needed the iteration starts; so Ite(1) holds the first adapted geometry):

\quad Loc(\textit{location name})Sce(\_\textit{scenario id})Pro(\_\textit{profile name})Ite(\_\textit{iteration index}).skx

\subsection{Generating input files for \DStability}
Older versions of \ProgramName used \DGeostability directly as kernel by generating \DGeostability input files (*.sti). 
These files were also made available to the user as they were written to the calculation folder 
(see \autoref{subsec:DataCommunicationStabilityKernel}).

These *.sti files made it possible to quickly and easily open the calculations in the actual program/kernel that was used to obtain the results (\DGeostability). 
This way, checking the final input to the kernel and even recalculating the results for an individual calculation was only a few mouse clicks away.

With the new \MacrostabilityKernel, 
the \ProgramName directly talks to the kernel itself, 
having no need to involve any UI program which would slow down the performance. 
However it still would be nice to be able to open, 
check and maybe even recalculate an individual calculation using such an UI. 
For this purpose, 
\DStability is the UI of choice as this is also uses the same kernel as \ProgramName does.

Therefore the \ProgramName is able to write files in the format that is used by \DStability which is the *.stix format. 
The actual writing of a stix file itself is done using an external tool (\StixWriter). 
This tool takes the input as defined in the \ProgramName for the kernel 
(via the C\# wrapper interface for the \MacrostabilityKernel) 
and writes the file at the specified place (i.e. the calculation folder).
Note that the resulting slip plane is added to the stix-file rather than just presenting the input. 
Main reason for this is that \DStability does not support \textit{Uplift Van} with search method \textit{Brute Force}. 
So it will never be able to reproduce the kernel results as found with \ProgramName.
By adding the resulting slip plane and changing the search method to \textit{Single Circle}, \DStability can reproduce the result.

For this reason, the \StixWriter is implemented in the post processing of the results.

\subsection{Mapping of the \ProgramName data}
\label{sec:MappingDamEngineDataMacrostability}
The \MacrostabilityKernel 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{Macrostability} StabilityModel  & \textbf{\ProgramName} DamInput.xsd \\ \hline
		MoveGrid & Fixed value: TRUE (default)  \\ \hline
		MaximumSliceWidth & Fixed value: 1.0 (default) \\ \hline
		SearchAlgorithm & DamMacroStabilityInput $\rightarrow$ FailureMechanismParametersMStab $\rightarrow$ MStabParameters $\rightarrow$ SearchMethod \\ \hline
		ModelOption & DamMacroStabilityInput $\rightarrow$ FailureMechanismParametersMStab $\rightarrow$ MStabParameters $\rightarrow$ Model \\ \hline
		Orientation & DamMacroStabilityInput $\rightarrow$ FailureMechanismParametersMStab $\rightarrow$ MStabParameters $\rightarrow$ GridPosition \\ \hline
		NumberOfRefinementsGrid & Fixed value: 2 \\ \hline 
		NumberOfRefinementsTangentLines & Fixed value: 2 \\ \hline 
		\hline		
		SoilModel $\rightarrow$ Soils & DamKernelInput $\rightarrow$ Location $\rightarrow$ SoilList (See \autoref{table-MappingDamEngineSoilsMacrostability})\\ \hline
		SoilProfile & DamKernelInput $\rightarrow$ SubSoilScenario $\rightarrow$ SoilProfile2D \\ \hline
		SurfaceLine & DamKernelInput $\rightarrow$ Location $\rightarrow$ SurfaceLine \\ \hline
		Location & DamKernelInput $\rightarrow$ Location (See \autoref{table-MappingDamEngineLocationMacrostability})\\ \hline
		PreconsolidationStresses & DO-NOT-IMPLEMENT \\ \hline
		UniformLoads & generated (based on Location $\rightarrow$ StabilityOptions $\rightarrow$ TrafficLoad) \\ \hline
		ConsolidationValues & generated (based on DamKernelInput $\rightarrow$ Location $\rightarrow$ TrafficLoadDegreeOfConsolidations) \\ \hline
		MultiplicationFactorsCPhiForUplift & DO-NOT-IMPLEMENT \\ \hline
		Waternets & generated  \\ \hline
		SpencerSlipPlanes & DO-NOT-IMPLEMENT \\ \hline
		BishopCalculationCircle & generated (based on DamMacroStabilityInput $\rightarrow$ FailureMechanismParametersMStab $\rightarrow$ MStabParameters $\rightarrow$ SlipCircleDefinition) \\ \hline
		UpliftVanCalculationGrid & generated (based on DamMacroStabilityInput $\rightarrow$ FailureMechanismParametersMStab $\rightarrow$ MStabParameters $\rightarrow$ SlipCircleDefinition) \\ \hline
		SlipPlaneConstraints & DO-NOT-IMPLEMENT (See \autoref{table-MappingDamEngineSlipPlaneConstraintsMacrostability}) \\ \hline
		BeeswarmAlgorithmOptions & Only for Uplift Van with Bee Swarm. \\ \hline
		GeneticAlgorithmOptions & DO-NOT-IMPLEMENT \\ \hline
		LevenbergMarquardtOptions & DO-NOT-IMPLEMENT \\ \hline
\end{tabular}
	\caption{\small Mapping of the \MacrostabilityKernel data to the \ProgramName.}
	\label{tab:MappingDamEngineDataMacrostability}
\end{table}

\begin{table}[H]
	\small
	\begin{tabular}{|p{50mm}|p{\textwidth-50mm-24pt}|} \hline
		\textbf{Macrostability} \newline PreprocessingInput & \textbf{DamKernelInput} \newline DamFailureMechanismeCalculationSpecification $\rightarrow$
                                                                  FailureMechanismParametersMStab $\rightarrow$
																																	MStabParameters $\rightarrow$ SlipCircleDefinition \\ \hline
		\multicolumn{2}{|l|}{\textbf{\textit{SearchAreaConditions}}} \\ \hline																												
		\quad AutoSearchArea & True if BishopSearchAreaDetermination or UpliftVanGridSizeDetermination is Automatic, False otherwise.  \\ \hline		
		\quad AutoTangentLines & False for Bishop (see \textbf{Note} below). True if UpliftVanTangentLinesDefinition is Automatic or OnBoundaryLines, False otherwise. \\ \hline
		\quad OnlyAbovePleistoceen & N.A. for Bishop. For Uplift-Van, True if UpliftVanTangentLinesDefinition = Automatic, False if UpliftVanTangentLinesDefinition = OnBoundaryLines. \\ \hline
		\quad MaxSpacingBetweenBoundaries & 0.8 m. \\ \hline
		\quad TangentLineZTop & Generated if TangentLinesDefinition is Specified, 0 otherwise (see \textbf{Note} below). \\ \hline
		\quad TangentLineZBottom & Generated if TangentLinesDefinition is Specified, 0 otherwise (see \textbf{Note} below). \\ \hline
		\quad TangentLineNumber & Generated if TangentLinesDefinition is Specified, 0 otherwise (see \textbf{Note} below).  \\ \hline		
		\multicolumn{2}{|l|}{\textbf{\textit{PreConstructionStages}}} \\ \hline
		\quad CreateWaternet & False (because is generated by DAM Engine, see \autoref{tab:MappingDamEngineDataMacrostability}).  \\ \hline
	\end{tabular}
	\caption{\small Mapping of the \MacrostabilityKernel PreprocessingInput to the DAM Engine Input}
	\label{tab:MappingDamEnginePreProcessMacrostability}
\end{table}

\Note{Parameter \textit{AutoSearchArea} in \autoref{tab:MappingDamEnginePreProcessMacrostability} does not work the same way for Bishop and Uplift-Van if this parameter is TRUE: \\
For Bishop, the grid and tangent lines are both automatically determined 
and if \textit{AutoTangentLines} is TRUE then the tangent lines will be overwritten by the tangent lines of the Uplift-Van model. \\
For Uplift-Van, only the left and right grids are automatically determined, not the tangent lines.}

\Note{The specified tangent lines settings \textit{TangentLineZTop}, \textit{TangentLineZBottom} and \textit{TangentLineNumber} 
in \autoref{tab:MappingDamEnginePreProcessMacrostability} are not converted to a list of tangent lines in the Preprocessing Output object of Macrostability preventing the input stix file to be created. 
It is therefore needed to specified the tangent lines in the object StabilityModel $\rightarrow$ BishopCalculationCircle/UpliftVanCalculationGrid $\rightarrow$ TangentLines $\rightarrow$ BoundaryHeights, see \autoref{tab:MappingDamEngineDataMacrostability}.}

\begin{table}[H]
	\small
	\begin{tabular}{|p{70mm}|p{\textwidth-70mm-24pt}|} \hline
		\textbf{Macrostability} Soil  & \textbf{\ProgramName} Soil \\ \hline
		Name & Name \\ \hline
		AbovePhreaticLevel & AbovePhreaticLevel \\ \hline
		BelowPhreaticLevel & BelowPhreaticLevel \\ \hline
		Cohesion & Cohesion \\ \hline
		FrictionAngle & FrictionAngle \\ \hline
		Dilatancy & FrictionAngle \\ \hline
		RatioCuPc & RatioCuPc \\ \hline
		StrengthIncreaseExponent & StrengthIncreaseExponent  \\ \hline
		ShearStrengthModel & ShearStrengthModel \\ \hline
		SigmaTauTable & SigmaTauCurve \\ \hline
		SuTable & SuTableCurve \\ \hline
		FixedSoilStress.POP & PoP \\ \hline
	\end{tabular}
	\caption{\small Mapping of the \MacrostabilityKernel Soils to the \ProgramName Soils.}
	\label{table-MappingDamEngineSoilsMacrostability}
\end{table}

The parameters defined in the following table for Location are all parameters that are used by the waternet creator of the \MacrostabilityKernel. They will not yet be implemented (as explained above).
\begin{table}[H]
	\small
	\begin{tabular}{|p{65mm}|p{\textwidth-65mm-24pt}|} \hline
		\textbf{Macrostability} Location  & \textbf{\ProgramName} Location \\ \hline
		DikeSoilScenario & TO-BE-ADDED \\ \hline
		WaterLevelRiver & Scenario $\rightarrow$ 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 $\rightarrow$ PlLineOffsetBelowDikeTopAtPolder \\ \hline
		PlLineOffsetBelowShoulderBaseInside & Scenario $\rightarrow$ PlLineOffsetBelowShoulderBaseInside \\ \hline
		PlLineOffsetBelowDikeToeAtPolder & Scenario $\rightarrow$ PlLineOffsetBelowShoulderBaseInside \\ \hline
		HeadInPLLine2Inwards & HeadPl2 \\ \hline
		HeadInPLLine3 & Scenario $\rightarrow$ HeadPl3 \\ \hline
		HeadInPLLine4 & Scenario $\rightarrow$ HeadPl4 \\ \hline
		AdjustPl3And4ForUplift & set to TRUE \\ \hline
		PenetrationLength & ModelParametersForPlLines $\rightarrow$ PenetrationLength \\ \hline
		LeakageLengthOutwardsPl3 & DO-NOT-IMPLEMENT \\ \hline
		LeakageLengthInwardsPl3 & generate based on ModelParametersForPlLines $\rightarrow$ DampingFactorPl3 \\ \hline
		LeakageLengthOutwardsPl4 & DO-NOT-IMPLEMENT \\ \hline
		LeakageLengthInwardsPl4 & generate based on ModelParametersForPlLines $\rightarrow$ DampingFactorPl4 \\ \hline
	\end{tabular}
	\caption{\small Mapping of the \MacrostabilityKernel Slip Plane Location to the \ProgramName Location.}
	\label{table-MappingDamEngineLocationMacrostability}
\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{Macrostability} Constraints  & \textbf{\ProgramName} Constraints \\ \hline
		SlipPlaneMinDepth & Location $\rightarrow$ StabiltiyOptions $\rightarrow$ 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 \MacrostabilityKernel Slip Plane Constraints to the \ProgramName  data.}
	\label{table-MappingDamEngineSlipPlaneConstraintsMacrostability}
\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 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 is at least one aquifer, a waternet line is created along the top of the bottom aquifer. \\
If Pl 4 exists it becomes a head line. If there are at least two aquifers, waternet lines are created along the top and bottom of the in-between aquifer(s). 

\subsection{Mapping of the validation result}
\label{sec:MappingValidationResultMacrostability}
The \MacrostabilityKernel 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{Macrostability} WTIStabilityModelValidation.xsd  & \textbf{\ProgramName} DamDesignResult.xsd $\rightarrow$ StabilityDesignResults \\ \hline
		Validations $\rightarrow$ ValidationsType & ResultMessage $\rightarrow$ LogMessageType\\ \hline
\end{tabular}
	\caption{\small Mapping of the \MacrostabilityKernel validation result to the \ProgramName.}
	\label{table-MappingValidationResultMacrostability}
\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:MappingCalculationResultMacrostability}
The \MacrostabilityKernel 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{Macrostability} WTIStabilityModelResult.xsd $\rightarrow$ WTIStabilityModelResult  & \textbf{\ProgramName} DamDesignResult.xsd $\rightarrow$ StabilityDesignResults \\ \hline
		Calculated & CalculationResult\\ \hline
		SafetyFactor & SafetyFactor\\ \hline
		Messages & ResultMessage\\ \hline
		MinimumSafetyCurve $\rightarrow$ first Slice, TopLeftPoint X & CircleSurfacePointLeftXCoordinate\\ \hline
		MinimumSafetyCurve $\rightarrow$ last Slice, TopRightPoint X & CircleSurfacePointRightXCoordinate\\ \hline
		ModelOption & StabilityModelType\\ \hline
\end{tabular}
	\caption{\small Mapping of the \MacrostabilityKernel validation result to the \ProgramName.}
	\label{table-MappingCalculationResultMacrostability}
\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}
