Index: dam engine/trunk/doc/Dam Engine - Technical Design/DAM Engine - Technical Design.tex =================================================================== diff -u -r179 -r212 --- dam engine/trunk/doc/Dam Engine - Technical Design/DAM Engine - Technical Design.tex (.../DAM Engine - Technical Design.tex) (revision 179) +++ dam engine/trunk/doc/Dam Engine - Technical Design/DAM Engine - Technical Design.tex (.../DAM Engine - Technical Design.tex) (revision 212) @@ -18,19 +18,19 @@ \reference{1210702-000-GEO-0004} \classification{-} -\date{Mar. 2017} -\version{0.2} +\date{Jun. 2017} +\version{0.3} \keywords{Dike, safety assessment, design, software, macro stability, piping} \references{Refer to \autoref{chapterLiterature}.} -\summary{This document contains the technical design for \ProgramName, a software module that computes the strength of a complete dikering with respect to several failure mechnanisms, such as macro stability and 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.\\ \\ \textbf{\footnotesize{Samenvatting}} \\ Dit document bevat het technisch ontwerp voor \ProgramName, een software module die een gebruiker in staat stelt om voor een dijktraject berekeningen uit te voeren voor verschillende faalmechanismen, waaronder macrostabiliteit en piping.} -\versioni{0.2} +\versioni{0.3} \datei{Mar 2017} \authori{Tom The} \revieweri{John Bokma \newline Andr\'e Grijze} @@ -54,7 +54,15 @@ 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} @@ -80,6 +88,8 @@ \end{table} \section{Document revisions} + +\section{Document revisions} \label{sec:DocumentRevisions} \subsection{Revision 0.1} \label{sec:Revision01} @@ -89,6 +99,10 @@ \label{sec:Revision02} Adapted based on reviews of this document by Jan Noort and Andr\'e Grijze. +\subsection{Revision 0.3} +\label{sec:Revision03} +Adapted based on review of this document by John Bokma. + %------------------------------------------------------------------------------ \chapter{System Architecture} \label{chapterSystemArchitecture} @@ -152,7 +166,7 @@ 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{Assessment} +\subsection{Dikes assessment} \begin{figure}[H] \begin{center} \includegraphics[width=15cm]{pictures/DAMEngineSequenceAssessment.pdf} @@ -169,7 +183,7 @@ \label{fig-DAMEngineActivityAssessment} \end{figure} -\subsection{Assessment Regional} +\subsection{Dikes assessment Regional} \begin{figure}[H] \begin{center} \includegraphics[width=15cm]{pictures/DAMEngineSequenceAssessmentRegional.pdf} @@ -186,7 +200,7 @@ \label{fig-DAMEngineActivityAssessmentRegional} \end{figure} -\subsection{Design} +\subsection{Dikes design} \begin{figure}[H] \begin{center} \includegraphics[width=15cm]{pictures/DAMEngineSequenceDesign.pdf} @@ -202,6 +216,28 @@ \caption{\small \ProgramName Design activity diagram.} \label{fig-DAMEngineDesignAssessment} \end{figure} + +\subsection{Dikes operational} +\begin{figure}[H] + \begin{center} + \includegraphics[width=15cm]{pictures/DAMEngineSequenceOperational.pdf} + \end{center} + \caption{\small \ProgramName Operational sequence diagram.} + \label{fig-DAMEngineSequenceOperational} +\end{figure} + +\begin{figure}[H] + \begin{center} + \includegraphics[width=8cm]{pictures/DAMEngineActivityOperational.pdf} + \end{center} + \caption{\small \ProgramName Operational activity diagram.} + \label{fig-DAMEngineActivityOperational} +\end{figure} + + +\subsection{Dikes NWO calculation} +This will not be part of the first implementation of \ProgramName and therefor this paragraph has not yet been written. + %------------------------------------------------------------------------------ \chapter{Architectural Choices} \label{chapterArchitecturalChoices} \section{Architecture guidelines} @@ -232,30 +268,47 @@ 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 (UK) +\end{itemize} +The mechanism to support other languages will be done through the standard Windows mechanism with language resource dll's. \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 Delta Shell Light (DSL); + \item Failure mechanisms. \item Math.NET. \end{itemize} Other libraries may be used under the condition that they are open source and free components, that are free to redistribute. \newline All libraries should be listed in a manifest accompanying the release of \ProgramName. The list should also specify under which license each specific library is distributed. -\subsection{DSL} \label{sec:DSL} -Delta Shell Light is a library that is used within Deltares, DSC. It is used by the \kernel WTIMacrostability. -Some data objects (e.g. Soil and Geometry) that are used by WTIMacrostability, can also be used in the \ProgramName. -The \ProgramName will only use part (the non-UI modules) of the DSL 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 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 DSL-Core - \item DSL-Probabilistic - \item DSL-Geo + \item Piping Bligh (not opensource) + \item Piping Sellmeijer VNK (not opensource) + \item Piping Sellmeijer 2 forces (not opensource) + \item D-Geo Stability inward (not opensource, but commerical) + \item D-Geo Stability outward (not opensource, but commerical) \end{itemize} -The use of DSL is free of cost and the components are free to redistribute. +After the original failure mechanisms have been implemented, the new WBI failure mechanisms will be added: +\begin{itemize} + \item WTI Piping + \item WTI Macrostability inward +\end{itemize} + \subsection{Math.Net} \label{sec:MathNet} Math.Net is a library that is distributed under the MIT/X11 license. Therefore it meets the conditions about open source and free redistribution. @@ -301,18 +354,44 @@ \section{Type enumerations} \label{sec:TypeEnumerations} \subsection{MainMechanismType} \begin{itemize} - \item Stability + \item Macrostability inward + \item Macrostability outward \item Piping \end{itemize} +\section{Scenarios} \label{sec:Scenarios} +Scenarios are widely (a)bused within DAM. It is good to define in which context scenarios are used and how they are to be called. Simply using the word sceanrio is not enough. +Within DAM we have 3 types of scenarios: +\begin{itemize} + \item Subsoil scenario + \item Load scenario + \item Regional scenario +\end{itemize} + +\subsection{Subsoil scenario} +\label{sec:SubSoilScenario} +Used as part of the stochastic subsoil schematization. +A subsoil scenario defines a possible 1D- or 2D-profile that applies to a certain location. + +\subsection{Load scenario} +\label{sec:LoadScenario} +Used for Design calculation. +In a design calculation a new surfaceline is designed for a location, based on a target failure factor (e.g. due to new requirements), or load (e.g. a higher waterlevel). + +\subsection{Regional scenario} +\label{sec:RegionalScenario} +For regional assessments there are certain scenarios that have to be evaluated, depending on the circumstances (e.g. drought, type of dike etc.). Part of the assessment is the determination which scenarios have to be evaluated and then calculating those scenarios. + \section{Main Data Model} \label{sec:MainDataModelDescription} \subsection{Input} \paragraph*{DamProjectType} \begin{itemize} \item Assessment - \item Design + \item Assessment regional \item Operational + \item Design + \item NWO \end{itemize} \paragraph*{DamProjectCalculationSpecification} This class specifies which failuremechanism is to be calculated and it also contains the specific options for the selelected mechanism (e.g.\ which calculation model) @@ -327,13 +406,13 @@ \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 containt 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). +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 is describes the dike profile in a specific location. In the Design calculation it can also be the new dike profile, which can meet design creteria in a specific load scenario. +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 load scenario. \paragraph*{WaternetOptions} The options that support the creation of a waternet in a specific location. \paragraph*{DesignOptions} @@ -357,6 +436,12 @@ \section{\ProgramName main modules} \label{sec:DAMEngineMainModules} +\subsection{Assessment Dikes} +This module performs an assessment for general dikes (e.g. primary dikes). +\paragraph*{Primary assessment calculation} +This is the main submodule of the primary assessement. +This submodule contains the main loop of the calculation. + \subsection{Assessment Regional Dikes} This module performs an assessment for regional dikes. \paragraph*{Regional assessment calculation} @@ -367,16 +452,19 @@ The scenarios are selected based on the local conditions. \paragraph*{Regional schematization factor calculator} This submodule calculates the schematization factor in a location based on all results of all scenarios in a location. -\subsection{Assessment Primary Dikes} -This module performs an assessment for primary dikes. -\paragraph*{Primary assessment calculation} -This is the main submodule of the primary assessement. -This submodule contains the main loop of the calculation. -\subsection{Design Primary Dikes} -This module performs an design calculation for primary dikes. + +\subsection{Design Dikes} +This module performs an design calculation for all types of dikes. \paragraph*{Primary design calculation} This is the main submodule of the primary design calculation. This submodule contains the main loop of the calculation. + +\subsection{Operation module} +This module performs a time series based calculation for all types of dikes. +\paragraph*{Time series based calculation} +This is the main submodule of the time series based calculation. +This submodule contains the main loop of the calculation. + \subsection{NWO Calculation} This module performs an NWO (Niet Waterkerende Objecten) calculation for primary dikes. \paragraph*{Primary NWO calculation} @@ -406,7 +494,8 @@ \subsubsection{Prepare} \label{sec:Prepare} -This method has one parameter +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. +This method has one parameter: \begin{itemize} \item Input \end{itemize} @@ -416,16 +505,20 @@ \subsubsection{Validate} \label{sec:Validate} -This method has 2 parameters +The purpose of this method is to validate the data that will be used as input for the failure mechanism. +This method has 2 parameters: \begin{itemize} \item IKernelDataInput (kernel input data) \item ValidationMessageList (a list of messages produced by the validation) \end{itemize} -It has no return value (void). +It returns an integer: +0: no errors. A calculation is possible. It is possible that there are warning messages. +>0: number of error messages that prevent a calculation. \subsubsection{Execute} \label{sec:Execute} -This method has 2 parameters +This method performs the actual calculation of the failure mechanism, +This method has 2 parameters: \begin{itemize} \item IKernelDataInput (kernel input data) \item ErrorMessageList (a list of error messages produced by the calculation) @@ -435,13 +528,15 @@ \subsubsection{Design} \label{sec:Design} -This method has 2 parameters +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 3 parameters: \begin{itemize} \item IKernelDataInput (kernel input data) + \item IKernelDesignDataInput (definition of the design parameters) \item ErrorMessageList (a list of error messages produced by the design calculation) \end{itemize} -It returns a IKernelDesignDataOutput. IKernelDesignDataOutput contains the new designed geometry and other design results (e.g. number of iterations needed, success or failure etc.). \newline -Based on certain design criteria a new design is determined, which will meet the required criteria. If such a design is not possible, that will be reported back. +It returns a IKernelDesignDataOutput. IKernelDesignDataOutput 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.). \newline +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} @@ -483,9 +578,9 @@ \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 shouldeer on the inside of the dike. +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 specifi place in the surfaceline. +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. @@ -513,7 +608,7 @@ The scripting engine has acces to the data model and the submodules through well defined interfaces. %------------------------------------------------------------------------------ -\chapter{Programing Interface} \label{chapterProgramingInterface} +\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.