\chapter{Introduction} 
\label{chapterIntroduction}

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

This document contains the functional 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 requirements and functional design of \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 (this document)  \newline  \citep{DAMEngine_FunctionalDesign} & Description of the requirements and functional design. \\ \hline
\ProgramName - Technical Design\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. (not available yet).  \\ \hline
\ProgramName - Test Report \newline \citep{DAMEngine_TestReport} & Description of the test results (benchmarks and test scripts)(not available yet). \\ \hline
Architecture Guidelines \newline \citep{ArchitectureGuidelines} & Architecture guidelines that are used by DSC-Deltares. \\ \hline
Overview of data used \newline \citep{DAMDataUIEngine} & Table with data used by DAM UI and\ProgramName\\ \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.

\chapter{Non-functional requirements}

\chapter{Functional requirements}

Main purpose of the \ProgramName is to get data from DAM Clients, uses this data as calculation input and make serially calculations with one ore more kernels and generates output. This can be broken down to the next use cases:\newline

Use case Design - UC Design\newline
As a user I want to adapt the geometry until given safety for stability or piping is met.

Use case Assessment - UC Assessment\newline
As a user I want to perform the assessment of regional dikes according to Leidraad Toetsen Regionale keringen.

Use case Operational sensors - UC Operational.sensors\newline
As a user I want to make stability and/or piping calculations with the input from operational sensors.

Since most requirements are needed for multiple use cases, the requirements are classified per theme, not per  Use Case. The themes are: data, calculation and output.
The requirements per Use case are given in next table.


\section{Data}

\subsection{REQ Data.Format}\label{sec:REQDataFormat}
The \ProgramName has a defined format for the data input, so DAM Clients know how to arrange the input data.

\subsection{REQ Data.Content}\label{sec:REQDataContent}
The \ProgramName has a defined content for the data input, so DAM Clients know how to arrange the input data.
The required data is described in xsd-files in https://repos.deltares.nl/ repos/ dam/ DamEngine/ trunk/ xsd.
An overview of the required data for the engine in relation to DAM UI data is described in https://repos.deltares.nl/ repos/ dam/ DamOverall/ trunk/ doc/ DAM General/ OverviewDataUIAndEngine.xlsx. In this Functional design is referred to parameters mentioned in this overview by giving the \textcolor[rgb]{0.65,0.16,0}{\textsl{name}}.

\section{Calculation}\label{sec:Calculation}

\subsection{Kernels}\label{sec:Kernels}
The \ProgramName provides calculations with the following  stability and piping kernels:
\begin{enumerate}
	\item Stability; kernel used by D-Geo Stability 15.1
	\item Stability; kernel used by D-Geo Stability 18.1
	\item \textsl{Stability; WBI-kernel stability}
	\item \textsl{Stability; kernel used by D-Geo Stability 2019}
	\item Piping; DAM-kernel piping
	\item \textit{Piping; WBI-kernel piping}
\end{enumerate}

Italic printed functionalities are not implemented in DAM yet.

\subsubsection{REQ Calc.Kernel15}\label{sec:REQ CalcKernel15}
The DAM engine can make stability calculations with the kernel of D-Geostability 15.1.
The options used by the DAM engine are described in \autoref{sec:UseStabKernel}.

\subsubsection{REQ Calc.Kernel18}\label{sec:REQ CalcKernel18}
The DAM engine can make stability calculations with the kernel of D-Geostability 18.1.
The options used by the DAM engine are equal to the use of the kernel of D-Geostability 15.1 and are described in \autoref{sec:UseStabKernel}.

\subsubsection{REQ Calc.DAMPiping}\label{sec:REQ CalcDAMPiping}
The DAM engine can make piping calculations with the DAM-piping kernel.
The functional design of the DAM piping kernel is described in \autoref{sec:FODAMPipingKernel}.


\subsubsection{REQ Calc.WBIPiping}\label{sec:REQ CalcWBIPiping}
The DAM engine can make piping calculations with the WBI-piping kernel.
The functional design of the DAM piping kernel is described in \autoref{sec:UseWBIPipingKernel}.


\subsection{REQ Calc.Assess.Regional}\label{sec:REQCalcAssessRegional}
For the assessment of regional dikes, \ProgramName must calculate several assessment scenarios (RRD-scenario). The design of this scenario selection is descriped in \autoref{sec:RRDScenarioSelection}.

\subsection{REQ Calc.Design.Geometry}\label{sec:REQDesignGeometry}
The DAM engine must be able to generate new profiles (surfacelines) based on a desired Dike table heigth (DTH) and/or Factor of safety. This can be done by:
\begin{enumerate}
 \item Raising the crest
 \item Reducing the gradient of the slope
 \item Shoulder development
\end{enumerate}

The design of this geometry adeption is described in \autoref{sec:DesignGeometryAdaption}

\subsection{REQ Calc.Operational.Sensor}\label{sec:REQOperationalSensor}
The DAM Engine must be able to use sensor data as input for the generation of water pressures.

\subsection{REQ Calc.Design.Excavation}\label{sec:REQDesignExcavation}
This will not be part of the implementation of DAM Engine and therefor this paragraph has
not yet been written.

\section{Output}
\label{sec:Output}

\subsection{REQ Output.format}\label{sec:REQOutputFormat}
The \ProgramName has a defined format for the data output, so DAM Clients know how to present the output data.


%The \ProgramName provides three types of major calculations:
%\begin{enumerate}[A.]
	%\item One-fold calculation: the input goes 'through' the kernel(s) and generates one main calculation answer (assessment and scenario);
	%\item Goal-seeking calculation: the input contains one variable and a desired outcome, the answer is the variable sufficient for the goal (design);
	%\item Time-lapsed calculation; calculations are made as time serie (operational).
%\end{enumerate}
%
%More specified; the \ProgramName provides the following calculation types, so the DAM Clients can provide this functionality.
%\begin{itemize}
	%\item Assessment regional dikes (type A); stability and piping.
	%\item Design of geometry, given required safety factor: Design-Geometry (type B); stability or piping.
	%\item Design of geometry, given dimensions of excavation and required safety factor: Design-Excavation (type B) \textit{Not implemented yet.}; stability or piping.
	%\item Operational calculation from sensor data (type C); stability or piping.
%\end{itemize}