Index: dam engine/trunk/doc/Dam Engine - Technical Design/DAM Engine - Technical Design.tex =================================================================== diff -u -r177 -r179 --- dam engine/trunk/doc/Dam Engine - Technical Design/DAM Engine - Technical Design.tex (.../DAM Engine - Technical Design.tex) (revision 177) +++ dam engine/trunk/doc/Dam Engine - Technical Design/DAM Engine - Technical Design.tex (.../DAM Engine - Technical Design.tex) (revision 179) @@ -25,15 +25,15 @@ \references{Refer to \autoref{chapterLiterature}.} -\summary{This document contains the technical design for \ProgramName, an application 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 mechnanisms, such as macro stability and piping.\\ \\ \textbf{\footnotesize{Samenvatting}} \\ -Dit document bevat het technisch ontwerp voor \ProgramName, een User Interface applicatie die een gebruiker in staat stelt om voor een dijktraject berekeningen uit te voeren voor verschillende faalmechanismen, waaronder macrostabiliteit en piping.} +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} \datei{Mar 2017} \authori{Tom The} -\revieweri{John Bokma} +\revieweri{John Bokma \newline Andr\'e Grijze} \approvali{Maya Sule} \status{draft} @@ -73,6 +73,7 @@ \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} @@ -91,6 +92,9 @@ %------------------------------------------------------------------------------ \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. @@ -176,9 +180,9 @@ \begin{figure}[H] \begin{center} - \includegraphics[width=8cm]{pictures/DAMEngineActivityAssessmentRegional.pdf} + \includegraphics[width=9cm]{pictures/DAMEngineActivityAssessmentRegional.pdf} \end{center} - \caption{\small \ProgramName Regionl assessment activity diagram.} + \caption{\small \ProgramName Regional assessment activity diagram.} \label{fig-DAMEngineActivityAssessmentRegional} \end{figure} @@ -200,15 +204,21 @@ \end{figure} %------------------------------------------------------------------------------ \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} \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 adapter classes will share a common ISurfacelineAdapter 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. @@ -220,39 +230,47 @@ \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 ouput XML file. \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}. -\section{External libraries and components} \label{sec:ExternalLibrariesAndComponents} -\ProgramName uses third-party libraries and components. Only open sources and free components, that are free to redistribute are allowed to be used. +\section{Libraries and components} \label{sec:ExternalLibrariesAndComponents} +\ProgramName uses other libraries and components. -Furthermore \ProgramName uses the Delta Shell Light (DSL) library, that is developed by Deltares. +For now we foresee only the use of the following libraries: +\begin{itemize} + \item Delta Shell Light (DSL); + \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. -\section{DSL} \label{sec:DSL} -The \ProgramName only uses part (the non-UI modules) of the DSL library +\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 \begin{itemize} \item DSL-Core \item DSL-Probabilistic \item DSL-Geo \end{itemize} +The use of DSL is free of cost and the components are free to redistribute. -\section{Other libraries} \label{sec:OtherLibraries} -Other libraries that are used bij the \ProgramName are: -\begin{itemize} - \item Math.Net: mathematical library -\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. - - %------------------------------------------------------------------------------ \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} @@ -277,9 +295,6 @@ \label{fig-DAMEngineDataModelLocation} \end{figure} - - - %------------------------------------------------------------------------------ \chapter{Data Description} \label{chapterDataDescription} @@ -316,15 +331,15 @@ \section{Location} \label{sec:LocationDescription} \paragraph*{SoilSegment} -A soil segment contains the subsoil data for a specific failure mechanism +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. \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 actaul sensor readings are defined as timeseries readings for each sensor in each location. +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*{LoadScenario} Used for Design calculation. A load scenario contains the following items: \begin{itemize} @@ -369,54 +384,131 @@ This submodule contains the main loop of the calculation. \section{\ProgramName supporting modules} \label{sec:DAMEngineSupportingModules} -\subsection{Failure mechanism wrappers} -These are calculation wrappers for each kernel to be implemented for each failure mechanism that is supported by the \ProgramName. -Each wrapper should implement the IFailureMechanism interface.\newline +\subsection{Failure mechanism wrapper interface} +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: -D-Geo Stability kernel has the ability to calculate the failure mechanism macrostability inwards en the failure mechanism macrostability outwards. -In this case 2 wrappers (one for each failure mechanism) are needed for this single kernel. -\paragraph*{Macrostability inwards} +D-Geo Stability kernel has the ability to calculate the failure mechanism macrostability inwards and the failure mechanism macrostability outwards. +In this case 2 wrappers (one for each failure mechanism) are 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} + +\subsubsection{Prepare} +\label{sec:Prepare} +This method has one parameter +\begin{itemize} + \item Input +\end{itemize} +It returns IKernelDataInput. This method fills the IKernelDataInput object from the main input data object (Input). +In IKernelDataInput the data is filled that is needed by the specific \kernel data. +Each \kernel wrapper will have its own implementation of IKernelDataInput. + +\subsubsection{Validate} +\label{sec:Validate} +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). + +\subsubsection{Execute} +\label{sec:Execute} +This method has 2 parameters +\begin{itemize} + \item IKernelDataInput (kernel input data) + \item ErrorMessageList (a list of error messages produced by the calculation) +\end{itemize} +It returns IKernelDataOutput. IKernelDataOutput contains the calculation results of the \kernel data. +Each \kernel wrapper will have its own implementation of IKernelDataOutput. + +\subsubsection{Design} +\label{sec:Design} +This method has 2 parameters +\begin{itemize} + \item IKernelDataInput (kernel input data) + \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. + + +\subsubsection{PostProcess} +\label{sec:PostProcess} +This method has 2 parameters +\begin{itemize} + \item IKernelDataOutput (kernel output data) + \item Output (the \ProgramName output data) +\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 D-Geo Stability) -\paragraph*{Macrostability outwards} +\subsubsection*{Macrostability outwards} Calculation wrapper for Macrostability outward. -\paragraph*{Piping} +\subsubsection*{Piping} Calculation wrapper for Piping. -\subsection{Surfaceline adapters} -A collection of surfaceline adapters to support the design calculation. -Each adapter should adhere to the ISurfaceLineAdapter interface. -\paragraph*{Surfaceline Adapter Height} +\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. -\paragraph*{Surfaceline Adapter Slope} +\subsubsection*{Surfaceline Designer Slope} Adapts the surfaceline by changing the slope of the dike on the inside. -\paragraph*{Surfaceline Adapter Shoulder} +\subsubsection*{Surfaceline Designer Shoulder} Adapts the surfaceline by adding a shoulder or enlarging the shouldeer on the inside of the dike. -\paragraph*{Surfaceline Adapter NWO} +\subsubsection*{Surfaceline Designer NWO} Adapts the surfaceline by adding a NWO on a specifi place in the surfaceline. -\subsection{Calculation Runner} +\subsubsection{Calculation Runner} \paragraph*{Failure mechanism Calculation Runner} This submodule calculates a specific failure mechanism by calling the IFailureMechanism interface of the wrapper implementation. -\paragraph*{Design Calculation Runner} -This submodule performs a design calculation for a specific failure mechanism by calling the IFailureMechanism interface and several surfaceline adapters through their ISurfacelineAdaptert interface. -\paragraph*{Operational Calculation Runner} +\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. -\paragraph*{Probabilistic Calculation Runner} +\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} -\paragraph*{Geometry creator} +\subsubsection*{Geometry creator} This submodule combines a surfaceline with a subsoil scenario. -The output is a gemetry that can be used by the failure mechanisms to perform a calculation. -\paragraph*{Waternet creator} -This submodule determines the waternet that will be used by the failure mechanisms. -At first only the DAM implementation will be used as a waternet creator. -Later on new implementations can be made. +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. -\subsection{Scripting engine} +\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.