\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 functionality should be implemented.
What 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.4} \label{sec:Revision04}
\todo{Describe new or changed features.}.\newline
\subsection{Revision 0.3} \label{sec:Revision03}
Textual and functional adaptations.\newline
\subsection{Revision 0.2} \label{sec:Revision02}
Textual adaptations.\newline
Assessment is removed from the requirements.
{sec:TLDegOfCo} added.
\subsection{Revision 0.1}
\label{sec:Revision01}
First concept of the document.

\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 story 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 sub profile in combination with a surface line and characteristic points on this line. 
The surface line defines the right, left and top limit of the geometry. 
The bottom limit is defined by the sub profile.  
The left side of the geometry 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 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{Creating calculation profiles}\label{sec:CreateCalculationProfiles}
In order to be able to perform any calculation, the \ProgramName needs to create the proper calculation profile by combining a given surface line with a given sub profile.
This sub profile can be a 1D-profile as well as a 2D-profile.

The combination of surface line and sub profile will always result in a 2D calculation profile. 
For stability calculations this profile is used as is,
for piping calculation this 2D-profile forms the base from which the 1D piping calculation profiles are obtained.
 
The way the combination is to be performed is described in \autoref{sec:CreatingCalculationProfiles}.

\subsection{Kernels}\label{sec:Kernels}
The \ProgramName provides calculations with the following stability and piping kernels:
\begin{enumerate}
	\item Stability; \MacroStabilityKernel
	\item Piping; WBI-kernel piping
\end{enumerate}

\subsubsection{REQ Calc.Kernel}\label{sec:REQ CalcKernel}
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}.


\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 WBI 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}