Index: DamEngine/trunk/doc/Dam Engine - Technical Design/DAM Engine - Technical Design.tex =================================================================== diff -u -r3427 -r3452 --- DamEngine/trunk/doc/Dam Engine - Technical Design/DAM Engine - Technical Design.tex (.../DAM Engine - Technical Design.tex) (revision 3427) +++ DamEngine/trunk/doc/Dam Engine - Technical Design/DAM Engine - Technical Design.tex (.../DAM Engine - Technical Design.tex) (revision 3452) @@ -13,7 +13,7 @@ \newcommand{\ProgramName}{DAM Engine\xspace} \newcommand{\kernel}{failuremechanism kernel\xspace} -\newcommand{\WbiKernel}{WBI macrostability kernel\xspace} +\newcommand{\MacrostabilityKernel}{Macrostability kernel\xspace} \newcommand{\DGeostability}{D-Geo Stability 18.1 kernel\xspace} \title{\ProgramName} \subtitle{Technical Design} @@ -65,7 +65,6 @@ 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} @@ -118,7 +117,7 @@ \label{sec:Revision05} \begin{itemize} \item Added a chapter on Failure Mechanism implementations. - \item Added description of the implementation of the WBI Macrostability kernel. + \item Added description of the implementation of the Macrostability kernel. \end{itemize} %------------------------------------------------------------------------------ @@ -304,17 +303,10 @@ \item Piping Bligh (not opensource). \item Piping Sellmeijer VNK (not opensource). \item Piping Sellmeijer 4 forces (not opensource). - \item D-Geo Stability inward (not opensource, but commercial). - \item D-Geo Stability outward (not opensource, but commercial). - \item D-Geo Horizontal Balance (not opensource, but commercial). + \item Piping Sellmeijer Revised (WBI). + \item Macrostability inward \end{itemize} -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. @@ -444,41 +436,33 @@ \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} -This is the main submodule of the regional assessement. -This submodule contains the main loop of the calculation. -\paragraph*{Regional scenario selector} -This submodule generates all the scenarios that have to be evaluated for a specific location. -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{Design Dikes} This module performs an design calculation for all types of dikes. -\paragraph*{Primary design calculation} +This module offers two types of analysis, \textit{No Adaption} and \textit{Adapt Geometry}. + +\paragraph*{Design calculation, No Adaption} This is the main submodule of the primary design calculation. This submodule contains the main loop of the calculation. +The calculations are performed with the data given as is. -\subsection{Operation module} -This module performs a time series based calculation for all types of dikes. +\paragraph*{Design calculation, Adapt Geometry} +This is the main submodule of the primary design calculation. +This submodule contains the main loop of the calculation. +In this option, +calculations are performed and then checked whether the required safety is met. +If the safety requirement is met, +the calculation for that item stops and returns its results. +When it is not, the geometry is adapted +(see /ToDo{describe geometry adaptions}) +until the safety requirement is met or possibilty to adapt further . + +\subsection{Calamity module} +This module (alos known as the Operational 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} -This is the main submodule of the NWO calculation. -This submodule contains the main loop of the calculation. - \section{\ProgramName supporting modules} \label{sec:DAMEngineSupportingModules} \subsection{Failure mechanism wrapper interface} \label{sec:FailureMechanismWrapperInterface} @@ -488,8 +472,8 @@ 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 and the failure mechanism macrostability outwards. -In this case 2 wrappers (one for each failure mechanism) are needed for this single kernel.\newline +\MacrostabilityKernel has the ability to calculate the failure mechanism macrostability inwards. +In this case 1 wrapper is needed for this single kernel.\newline The next methods are defined in the IFailureMechanism interface \begin{itemize} \item Prepare() @@ -503,7 +487,7 @@ Next to that, each wrapper can have properties that hold data that are specific to the failure mechanism.\newline Example: -D-Geostability needs parameters specifying the grid, tangent lines et. These can be passed as properties to the wrapper directly.\newline +\MacrostabilityKernel needs parameters specifying the grid, tangent lines et. These can be passed as properties to the wrapper directly.\newline \subsubsection{Prepare} \label{sec:Prepare} @@ -632,9 +616,9 @@ \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) +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 \MacrostabilityKernel) \subsubsection*{Macrostability outwards} -Calculation wrapper for Macrostability outward. +Calculation wrapper for Macrostability outward (future). \subsubsection*{Piping} Calculation wrapper for Piping. \subsection{Surfaceline designers} @@ -842,31 +826,22 @@ \label{sec:PipingSellmeijerVNK} TODO... -\section{WBI Piping Sellmeijer Revised} +\section{Piping Sellmeijer Revised (WBI)} \label{sec:WBIPipingSellmeijerRevised} TODO... \section{Macrostability Inwards} \label{sec:MacrostabilityInwards} -TODO... +The macrostability kernel is used to support failure mechanism. +A Functional Design \citep{Zwan2017a} and a Technical Design \citep{MacroStabilityKernel_TechnicalDesign} is available. +Currently this kernel only supports macrostability inwards for the model Uplift Van. -\section{Macrostability Outwards} -\label{sec:MacrostabilityOutwards} -TODO... - -\section{Macrostability Horizontal Balance} -\label{sec:MacrostabilityHorizontalBalance} -TODO... - -\section{WBI Macrostability Inwards} -\label{sec:WbiMacrostabilityInwards} -For WBI a new macrostability kernel has been build. A Functional Design \citep{Zwan2017a} and a Technical Design \citep{MacroStabilityKernel_TechnicalDesign} is available. Currently this kernel only supports macrostability inwards for the model Uplift Van. The API of this kernel is based on an XML file that contains all the necessary data for the input of the kernel. The XML is defined with a set of XML schema's (XSD's). These XSD's can be found in chapter 2.3 of the Technical Design \citep{MacroStabilityKernel_TechnicalDesign}. \subsection{Initial implementation} \label{sec:InitialImplementation} -The first implementation of the \WbiKernel will not be a full implementation. It will implement the same options that were implemented in the original Macrostability Inwards implementation (which uses the \DGeostability).\newline -Therefore the following input options (see \autoref{sec:MappingDamEngineDataWbiMacrostability}) will not be implemented: +The first implementation of the \MacrostabilityKernel will not be a full implementation. It will implement the same options that were implemented in the original Macrostability Inwards implementation (which uses the \DGeostability).\newline +Therefore the following input options (see \autoref{sec:MappingDamEngineDataMacrostability}) will not be implemented: \begin{itemize} \item PreconsolidationStresses \item ConsolidationValues @@ -877,44 +852,94 @@ \item LevenbergMarquardtOptions \item Waternet creation options (defined in Location) \end{itemize} -Furthermore, no Waternet Daily will be specified. This was introduced in the \WbiKernel when POP is requested. -Also in the first implementation the waternet will be created by the \ProgramName. The waternet creator of the \WbiKernel will not be used. So the parameters used for the waternet creation do not have to be filled in when calling the \WbiKernel. Those are the parameters defined in \autoref{table-MappingDamEngineLocationWbiMacrostability}. +Furthermore, no Waternet Daily will be specified. This was introduced in the \MacrostabilityKernel when POP is requested. +Also in the first implementation the waternet will be created by the \ProgramName. The waternet creator of the \MacrostabilityKernel will not be used. So the parameters used for the waternet creation do not have to be filled in when calling the \MacrostabilityKernel. Those are the parameters defined in \autoref{table-MappingDamEngineLocationMacrostability}. +\subsection{Data communication between \ProgramName and \MacrostabilityKernel} +\label{subsec:DataCommunicationStabilityKernel} +The data is transferred from the \ProgramName to the \MacrostabilityKernel in memory to get the best performance in terms of speed. +However, the data is written to files using the proper calculation folder in Macro Stability kernel XML format (*.skx) too. + +The proper calculation folder is defined as : \\ + +\quad \textit{current project folder}\textbackslash \textit{projectname}.Calc\textbackslash \textit{failuremechanisme}\textbackslash \textit{model}\textbackslash + +where:\\ +\begin{itemize} + \item textit{current project folder} is the folder where your project resides. + \item \textit{projectname} is the name of your project + \item \textit{failuremechanisme} is the used failure mechanism such as Stabilty or Piping. + \item textit{model} is the used model such as UpliftVan or Bligh +\end{itemize} + +To be able to tell what file belongs to which calculation, the following naming convention is used: + +\quad Loc(\textit{location name})Sce(\_\textit{scenario id})Pro(\_\textit{profile name}).skx + +When a Design calculation is made with possible adaption of the geometry, the name will also display the iteration index when required (the very first unadapted calculation will be named as above, when adapation is needed the iteration starts; so Ite(1) holds the first adapted geometry): + +\quad Loc(\textit{location name})Sce(\_\textit{scenario id})Pro(\_\textit{profile name})Ite(\_\textit{iteration index}).skx + +\subsection{Generating input files for D-Stability} +Older versions of \ProgramName used \DGeostability directly as kernel by generating \DGeostability input files (*.sti). +These files were also made available to the user as they were written to the calculation folder +(see \autoref{subsec:DataCommunicationStabilityKernel}). + +These *.sti files made it possible to quickly and easily open the calculations in the actual program/kernel that was used to obtain the results (\DGeostability). +This way, checking the final input to the kernel and even recalculating the results for an individual calculation was only a few mouse clicks away. + +With the new \MacrostabilityKernel, +the \ProgramName directly talks to the kernel itself, +having no need to involve any UI program which would slow down the performance. +However it still would be nice to be able to open, +check and maybe even recalculate an individual calculation using such an UI. +For this purpose, +DStability is the UI of choice as this is also uses the same kernel as \ProgramName does. + +Therefore the \ProgramName must be able to write files in the format that is used by DStability which is the *.stix format. +The actual writing of a stix file itself is done using an external tool (MacroStability Six File Writer). +This tool takes the input as defined in the \ProgramName for the kernel (via the C\# wrapper interface for the \MacrostabilityKernel) +and writes the file at the specified place +(i.e. the calculation folder). + +The most logical place to implement this tool in the engine is there where the input for the \MacrostabilityKernel is generated. +That input is used for both the kernel (as input for the calculation) and for the stix file writer tool (to write the stix file). + \subsection{Mapping of the \ProgramName data} -\label{sec:MappingDamEngineDataWbiMacrostability} -The \WbiKernel has to be filled with input, that can be obtained from the \ProgramName data. In the following tables a mapping of the needed data to the \ProgramName data is defined. The data is contained in the classes DamKernelInput and DamMacroStabilityInput. +\label{sec:MappingDamEngineDataMacrostability} +The \MacrostabilityKernel has to be filled with input, that can be obtained from the \ProgramName data. In the following tables a mapping of the needed data to the \ProgramName data is defined. The data is contained in the classes DamKernelInput and DamMacroStabilityInput. \begin{table}[H] \small \begin{tabular}{|p{60mm}|p{\textwidth-60mm-24pt}|} \hline - \textbf{WBI Macrostability} StabilityModel & \textbf{\ProgramName} DamInput.xsd \\ \hline + \textbf{Macrostability} StabilityModel & \textbf{\ProgramName} DamInput.xsd \\ \hline MoveGrid & Fixed value: TRUE (default) \\ \hline MaximumSliceWidth & Fixed value: 1.0 (default) \\ \hline SearchAlgorithm & DamMacroStabilityInput -> FailureMechanismParametersMStab -> MStabParameters -> SearchMethod \\ \hline ModelOption & DamMacroStabilityInput -> FailureMechanismParametersMStab -> MStabParameters -> Model \\ \hline Orientation & DamMacroStabilityInput -> FailureMechanismParametersMStab -> MStabParameters -> GridPosition \\ \hline \hline - SoilModel -> Soils & DamKernelInput -> Location -> SoilList (See \autoref{table-MappingDamEngineSoilsWbiMacrostability})\\ \hline + SoilModel -> Soils & DamKernelInput -> Location -> SoilList (See \autoref{table-MappingDamEngineSoilsMacrostability})\\ \hline SoilProfile & DamKernelInput -> SubSoilScenario -> SoilProfile2D \\ \hline SurfaceLine & DamKernelInput -> Location -> SurfaceLine \\ \hline - Location & DamKernelInput -> Location (See \autoref{table-MappingDamEngineLocationWbiMacrostability})\\ \hline + Location & DamKernelInput -> Location (See \autoref{table-MappingDamEngineLocationMacrostability})\\ \hline PreconsolidationStresses & DO-NOT-IMPLEMENT \\ \hline UniformLoads & generated (based on Location -> StabilityOptions -> Trafficload) \\ \hline ConsolidationValues & DO-NOT-IMPLEMENT \\ \hline MultiplicationFactorsCPhiForUplift & DO-NOT-IMPLEMENT \\ \hline Waternets & generated \\ \hline SpencerSlipPlanes & DO-NOT-IMPLEMENT \\ \hline UpliftVanCalculationGrid & generated \\ \hline - SlipPlaneConstraints & DO-NOT-IMPLEMENT (See \autoref{table-MappingDamEngineSlipPlaneConstraintsWbiMacrostability}) \\ \hline + SlipPlaneConstraints & DO-NOT-IMPLEMENT (See \autoref{table-MappingDamEngineSlipPlaneConstraintsMacrostability}) \\ \hline GeneticAlgorithmOptions & DO-NOT-IMPLEMENT \\ \hline LevenbergMarquardtOptions & DO-NOT-IMPLEMENT \\ \hline \end{tabular} - \caption{\small Mapping of the \WbiKernel data to the \ProgramName.} - \label{table-MappingDamEngineDataWbiMacrostability} + \caption{\small Mapping of the \MacrostabilityKernel data to the \ProgramName.} + \label{table-MappingDamEngineDataMacrostability} \end{table} \begin{table}[H] \small \begin{tabular}{|p{70mm}|p{\textwidth-70mm-24pt}|} \hline - \textbf{WBI Macrostability} Soil & \textbf{\ProgramName} Soil \\ \hline + \textbf{Macrostability} Soil & \textbf{\ProgramName} Soil \\ \hline AbovePhreaticLevel & AbovePhreaticLevel \\ \hline BelowPhreaticLevel & BelowPhreaticLevel \\ \hline DilatancyType & DilatancyType \\ \hline @@ -925,14 +950,14 @@ OCR & OCR \\ \hline ShearStrengthModel & ShearStrengthModel \\ \hline \end{tabular} - \caption{\small Mapping of the \WbiKernel Soils to the \ProgramName Soils.} - \label{table-MappingDamEngineSoilsWbiMacrostability} + \caption{\small Mapping of the \MacrostabilityKernel Soils to the \ProgramName Soils.} + \label{table-MappingDamEngineSoilsMacrostability} \end{table} -The parameters defined in the following table for Location are all parameters that are used by the waternet creator of the \WbiKernel. They will not yet be implemented (as explained above). +The parameters defined in the following table for Location are all parameters that are used by the waternet creator of the \MacrostabilityKernel. They will not yet be implemented (as explained above). \begin{table}[H] \small \begin{tabular}{|p{65mm}|p{\textwidth-65mm-24pt}|} \hline - \textbf{WBI Macrostability} Location & \textbf{\ProgramName} Location \\ \hline + \textbf{Macrostability} Location & \textbf{\ProgramName} Location \\ \hline DikeSoilScenario & TO-BE-ADDED \\ \hline WaterLevelRiver & Scenario -> RiverLevel \\ \hline WaterLevelRiverAverage & TO-BE-ADDED \\ \hline @@ -958,14 +983,14 @@ LeakageLengthOutwardsPl4 & DO-NOT-IMPLEMENT \\ \hline LeakageLengthInwardsPl4 & generate based on ModelParametersForPlLines -> DampingFactorPl4 \\ \hline \end{tabular} - \caption{\small Mapping of the \WbiKernel Slip Plane Location to the \ProgramName Location.} - \label{table-MappingDamEngineLocationWbiMacrostability} + \caption{\small Mapping of the \MacrostabilityKernel Slip Plane Location to the \ProgramName Location.} + \label{table-MappingDamEngineLocationMacrostability} \end{table} The parameters defined in the following table for Constraints will not yet be implemented (as explained above). \begin{table}[H] \small \begin{tabular}{|p{70mm}|p{\textwidth-70mm-24pt}|} \hline - \textbf{WBI Macrostability} Constraints & \textbf{\ProgramName} Constraints \\ \hline + \textbf{Macrostability} Constraints & \textbf{\ProgramName} Constraints \\ \hline SlipPlaneMinDepth & Location -> StabiltiyOptions -> MinimumCircleDepth \\ \hline SlipPlaneMinLength & TO-BE-ADDED \\ \hline CreateZones & TO-BE-ADDED \\ \hline @@ -975,14 +1000,14 @@ MaxAllowedAngleBetweenSlices & TO-BE-ADDED \\ \hline RequiredForcePointsInSlices & TO-BE-ADDED \\ \hline \end{tabular} - \caption{\small Mapping of the \WbiKernel Slip Plane Constraints to the \ProgramName data.} - \label{table-MappingDamEngineSlipPlaneConstraintsWbiMacrostability} + \caption{\small Mapping of the \MacrostabilityKernel Slip Plane Constraints to the \ProgramName data.} + \label{table-MappingDamEngineSlipPlaneConstraintsMacrostability} \end{table} \subsubsection{Mapping of pl lines to waternet} \label{sec:MappingPlLinesToWaternet} -Dam Engine has a set of pl lines: Pl 1, Pl 2, Pl 3, Pl 4. Pl 1 is the phreatic line and it always exists. The other pl lines are optional. The pl lines from the Dam Engine are converted to a waternet that can be used in WBI Macrostability. +Dam Engine has a set of pl lines: Pl 1, Pl 2, Pl 3, Pl 4. Pl 1 is the phreatic line and it always exists. The other pl lines are optional. The pl lines from the Dam Engine are converted to a waternet that can be used in Macrostability. The waternet consists of a phreatic line, a list of head lines and a list of waternet lines. Each waternet line can have an associated head line. To create the waternet lines the soil profile data is used to determine the 'bottom aquifer' (the lowest set of one or more connected aquifer layers) and the 'in-between aquifer' (the first aquifer (layer set) that lies above the bottom aquifer). @@ -993,35 +1018,35 @@ If Pl 4 exists it becomes a head line. If there is at least one aquifer, a waternet line is created along the top of the bottom aquifer. \\ \subsection{Mapping of the validation result} -\label{sec:MappingValidationResultWbiMacrostability} -The \WbiKernel returns the validation result when the Validate function is called. In the following table a mapping of the validation result to the \ProgramName data is defined. +\label{sec:MappingValidationResultMacrostability} +The \MacrostabilityKernel returns the validation result when the Validate function is called. In the following table a mapping of the validation result to the \ProgramName data is defined. \begin{table}[H] \small \begin{tabular}{|p{60mm}|p{\textwidth-60mm-24pt}|} \hline - \textbf{WBI Macrostability} WTIStabilityModelValidation.xsd & \textbf{\ProgramName} DamDesignResult.xsd -> StabilityDesignResults \\ \hline + \textbf{Macrostability} WTIStabilityModelValidation.xsd & \textbf{\ProgramName} DamDesignResult.xsd -> StabilityDesignResults \\ \hline Validations -> ValidationsType & ResultMessage -> LogMessageType\\ \hline \end{tabular} - \caption{\small Mapping of the \WbiKernel validation result to the \ProgramName.} - \label{table-MappingValidationResultWbiMacrostability} + \caption{\small Mapping of the \MacrostabilityKernel validation result to the \ProgramName.} + \label{table-MappingValidationResultMacrostability} \end{table} When the Validations part is empty it means that the input is Valid. When there are one or more validations, they are added to the messages of the design results. The type of message can be Info, Warning or Error. The validation fails when there is at least one Error message. \subsection{Mapping of the calculation result} -\label{sec:MappingCalculationResultWbiMacrostability} -The \WbiKernel returns the calculation result when the Run function is called. In the following table a mapping of the calculation result to the \ProgramName data is defined. For now, only the parts that we currently use are described. +\label{sec:MappingCalculationResultMacrostability} +The \MacrostabilityKernel returns the calculation result when the Run function is called. In the following table a mapping of the calculation result to the \ProgramName data is defined. For now, only the parts that we currently use are described. \begin{table}[H] \small \begin{tabular}{|p{60mm}|p{\textwidth-60mm-24pt}|} \hline - \textbf{WBI Macrostability} WTIStabilityModelResult.xsd -> WTIStabilityModelResult & \textbf{\ProgramName} DamDesignResult.xsd -> StabilityDesignResults \\ \hline + \textbf{Macrostability} WTIStabilityModelResult.xsd -> WTIStabilityModelResult & \textbf{\ProgramName} DamDesignResult.xsd -> StabilityDesignResults \\ \hline Calculated & CalculationResult\\ \hline SafetyFactor & SafetyFactor\\ \hline Messages & ResultMessage\\ \hline MinimumSafetyCurve -> first Slice, TopLeftPoint X & CircleSurfacePointLeftXCoordinate\\ \hline MinimumSafetyCurve -> last Slice, TopRightPoint X & CircleSurfacePointRightXCoordinate\\ \hline ModelOption & StabilityModelType\\ \hline \end{tabular} - \caption{\small Mapping of the \WbiKernel validation result to the \ProgramName.} - \label{table-MappingCalculationResultWbiMacrostability} + \caption{\small Mapping of the \MacrostabilityKernel validation result to the \ProgramName.} + \label{table-MappingCalculationResultMacrostability} \end{table} Calculated is a boolean. When Calculated is true the CalculationResult is Succeeded, otherwise RunFailed. The type of message can be Info, Warning or Error.