\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. So it is clear what the purpose of \ProgramName is and which functionaliry
What will actually will be implemented depends on the prioritizing of the requirements by 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}\label{sec:DocumentRevisions}
\subsection{Revision 0.1}
\label{sec:Revision01}
First concept of the document.
\subsection{Revision 0.2} \label{sec:Revision02}
Textual adaptations.\newline
Assessment is removed from the requirements.
{sec:TLDegOfCo} added.
\subsection{Revision 0.3} \label{sec:Revision03}
Textual and functional adaptations.\newline

\chapter{Functional requirements}

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

User story Design\newline
As a user I want to adapt the geometry until given safety for stability or piping is met.

User stort 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 both user stories, the requirements are classified per theme, not per User story. 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}

\subsubsection{Location}\label{sec:REQDataFormatLocation}
Locations are defined by a unique name and RD coordinates.

\subsubsection{Geometry}\label{sec:REQDataFormatGeometry}
The geometry is defined by a surfaceline and characteristicpoints on this surfaceline. The surfaceline is limited by a surfaceleveloutside at the left side and surfaceline inside at the right sight. 
The left side of the geomtry is the riverside and the side of the variable waterlevel outside. The right side is the polderside (inside).

\subsubsection{Subsoil}\label{sec:REQDataFormatSubsoil}
The subsoil is defined by line shaped segments. Each segment is defined by one or more soilprofiles with a probability (sums up to 100\%). And a soilprofile describes the boundaries of the layers and their material. 

\subsubsection{Water pressures}\label{sec:REQDataFormatWaterpressure}
\ProgramName can schematize water pressures for piping and stability kernels, see \autoref{sec:GenerationPorePressures}.
Data needed for this schematization consists of waterlevels and the schematization parameter water pressure per layer.

\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 refered 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; \MacroStabilityKernel
	\item Piping; DAM-kernel piping
	\item Piping; WBI-kernel piping
\end{enumerate}

\subsubsection{REQ Calc.Kernel22}\label{sec:REQ CalcKernel22}
The DAM engine can make stability calculations with the \MacroStabilityKernel. 
The options used by the DAM engine are a subset of the use of that kernel and are described in \autoref{sec:UseStabKernel}.

% ToDo ToDo MWDAM-1719 {sec:FODAMPipingKernel} is defined in FOWBIPipingKernel.tex but this LaTeX-file is never included.
% Investigate if this subsection is relevant.
\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.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}
\textit{<This section will describe what kind of output \ProgramName can provide.>}

%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}