\chapter{Creating calculation profiles} \label{sec:CreatingCalculationProfiles}
The starting point for combining a surface line with a subsoil profile is that both contain only valid data. 
The goal of the combination is to create the final 2D-profile (= 2D-geometry + layer information) to be used in the calculation.

For stability calculations, this profile is used as is.
For piping calculations, this profile forms the base from which the 1D piping calculation profiles are obtained.

Next to the surface line and a subsoil profile, a filling material needs to be given. 
This material will be assigned to all surfaces of the new calculation profile for which a matching surface could not be found within the given subsoil profile.
When a matching surface could be found within the given subsoil profile, the material of that surface will be assigned to the new surface.

To explain the combination, a number of important definitions will follow first.

\section{Surface line geometry definition}
The geometry of a surface line consists of a series of points. 
Within the given local X-Z coordinate system, the X-coordinates must strictly increase (i.e., from left to right). 
Therefore, decreasing X-coordinates as well as equal X-coordinates are not allowed.

Note that a surface line holds not only the geometry but also definitions for point characteristics.
For the purpose of creating calculation profiles, only the geometry plays a role. 

\section{1D subsoil profile definition}
A 1D subsoil profile consists of a series of values for layer levels (in m to reference level) that decrease with depth.
A 1D subsoil profile is hence defined from top to bottom.

The first value is the top of the top 1D-layer, the second value is the top of the second 1-D layer and thus the bottom of the top 1D-layer, and so on. 
In principle, only one value (for the top of the top layer) is sufficient because DAM automatically adds a layer 20 meters below the lowest specified level.

For each layer, the name of the layer material must be specified. 
This name must match one material with properties as recorded elsewhere.

Note that a layer has other properties as well (e.g. IsAquifer) but these do not play a part in the combining process. 

\section{2D subsoil profile definition}
The important definitions regarding the geometry of the 2D subsoil profile are: 
\begin{itemize} 
	\item \textit{point}: is a point with two coordinates, an X and a Z coordinate. 
	\item \textit{curve}: is a line segment consisting of two points. 
	\item \textit{loop}: is a closed ring of at least 3 curves. 
	\item \textit{surface}: is a plane with 1 outer loop (an enclosing loop) and 0 or more inner loops (a loop entirely within an outer loop). 
\end{itemize}

Each point, curve, loop, and surface must be unique. 
Each point can occur in multiple curves (and thus in loops and surfaces). 
Each curve can occur in multiple loops (and thus in surfaces). 
Each inner loop must fall entirely within the outer loop and may not cross or even touch it anywhere. 
An inner loop can only share points with other possible inner loops in the same plane. 
An inner loop can only share line segments with other possible inner loops in the same plane.

A valid geometry contains: 
\begin{itemize} 
	\item at least 1 surface with at least 1 valid outer loop. 
	\item only the loops that are actually in use as an outer loop or one of the inner loops of a surface. 
	\item only curves that are actually in use in an outer loop or inner loop. 
	\item only points that are actually in use in a used curve (and by extension in a loop and surface). 
\end{itemize}

A point is only valid if both coordinates are known and it does not coincide with another point.
A curve is only valid if it contains two different existing points and does not coincide with another curve. 
Note that the order of the two curve points does not matter (comparing curve A head-point, endpoint with 
curve B head-point, endpoint is the same as comparing curve A head-point, endpoints with 
curve B endpoint, head-point and as curve A endpoint, head-point with curve B head-point, endpoints and 
even curve A endpoint, head-point with curve B endpoint, head-point).

A loop is only valid if: 
\begin{itemize} 
	\item there are at least 3 non-coinciding existing curves (there is an enclosed area). 
	\item it is not intersected by other curves and/or loops. 
	\item it does not contain coinciding curves and/or points.
	\item all curves are connected in such a way they form an enclosed area 
\end{itemize}

Next to the geometry, a 2D subsoil profile also contains a separate list of 2D-layers.
Each 2D-layer holds a surface (as reference to a geometry surface) and a material name.
This name must match one material with properties as recorded elsewhere.

\section{Combining a 1D subsoil profile with a surface line geometry}
To create a calculation profile, one option is by combining a 1D subsoil profile with a surface line geometry.

If the surface line geometry lies entirely below the 1D subsoil profile, no combination can be made. 
A calculation cannot be made for this situation, and an error message will follow. 
This error message will not interrupt the entire DAM process; the message will be recorded in the log file.

For merging a surface line geometry with a 1D subsoil profile, the surface line geometry is leading. 
This determines the left boundary (X-coordinate of the first point in the surface line geometry) of the 2D calculation profile to be created. 
It also determines its right boundary (X-coordinate of the last point in the surface line geometry).
Finally, the surface line geometry defines the top of the new 2D profile.

The process consists of: 
\begin{itemize} 
	\item Make a complete copy (clone) of both the 1D subsoil profile and the surface line geometry to prevent the original data from being changed. 
	\item Then perform all subsequent steps on the copies. 
	\item Add a very thick layer of the specified filling material above the original top layer of the 1D subsoil profile. 
	\item Check that the bottom layer has height. If not, add a 20 m thick layer. For this layer, use the material of the layer above it. 
	\item Determine all intersection points of the surface line geometry with the 1D subsoil profile. 
	\item Put all intersection points together with all points of the surface line geometry into one list of points, sorted by X-coordinate. 
	\item Using that list and the 1D subsoil profile, create a list of new 2D layers 
	(rectangular layers for all layers below the surface line geometry, multi-point layers for the 1D layers intersected by the surface line geometry; 
	everything above the surface line geometry is ignored). 
	Each 2D layer contains, in addition to the points, line segments, loop, and surface, the other layer information (IsAquifer, material, WaterpressureInterpolationModel). 
	\item Create an empty 2D geometry. 
	\item Set the left and right boundaries of this 2D geometry based on the surface line geometry. 
	\item Set the bottom boundary of this 2D geometry based on the 1D subsoil profile. 
	\item Add the list of sorted intersection points to the 2D geometry as NewlyEffectedPoints.
	\item Generate curves based on the intersection points and add these as  NewlyEffectedCurves.
	\item Note that the NewlyEffectedPoints and NewlyEffectedCurves form the basis of the (re-)generation process for a 2D geometry. 
	These lists are used to separate existing geometry points and curves from new points and curves during the regeneration process. 
	For this a general method is used that works for entirely new geometries 
	(generation, where all points and curves are new) as well as for editing existing geometries 
	(re-generation, where existing points/curves/loops/surfaces are combined with new points and curves).
	\item Add the list of 2D layers to the 2D geometry (avoid duplicate points and line segments!) as NewlyEffectedPoints, NewlyEffectedCurves. 
	\item Generate the 2D geometry based on the boundaries and “new” points and line segments (see \autoref{sec:Regenerating2DGeometry}). 
	\item Add all layer properties to the generated surfaces of the new 2D geometry based on the 2D layers list. 
	\item Create a new 2D (calculation) profile. 
	\item Add the 2D geometry to the 2D profile. 
	\item Finally, add all 2D layers (surfaces with info) to the 2D profile. 
\end{itemize}

The resulting 2D profile can never contain inner loops and has at least one valid surface with associated layer information. 

\section{Combining a 2D subsoil profile with a surface line geometry}
To create a calculation profile, another option is by combining a 2D subsoil profile with a surface line geometry.

Here too, the surface line geometry is leading in the combination process.
It determines the left boundary, the right boundary and the top of the 2D calculation profile to be created. 

If the surface line geometry lies entirely to the left or to the right of the 2D subsoil profile, a combination cannot be made. 
If the surface line geometry lies even partially below the 2D subsoil profile, no combination can be made. 
In both cases, a calculation cannot be made and an error message will follow. 
This error message will not interrupt the entire DAM process; the message will be recorded in the log file.

The process consists of: 
\begin{itemize} 
	\item Check that the 2D subsoil profile is not null and has at least 1 valid surface.
	\item Check that the surface line geometry is not null and contains at least 2 points.
	\item Check that the filling material and the surface line geometry are defined properly (e.g. are points ordered correctly).
	\item Check that the surface line geometry lies completely above the bottom of the 2D subsoil geometry.
	\item Check that the surface line geometry does not lie completely to the left or to the right of the 2D subsoil geometry.
	\item Make a complete copy (clone) of both the 2D subsoil profile and the surface line geometry to prevent the original data from being changed. 
	\item Then perform all subsequent steps on the copies. 
	\item Round all coordinates from both the 2D subsoil profile as well as from the surface line geometry to 3 decimals.
	\item Create a new 2D profile as place holder for the resulting calculation profile.
	\item Create a new 2D geometry by combining the surface line geometry with the subsoil profile (see \autoref{sec:Creating2DGeometry}).
	\item Add the generated 2D geometry to the 2D profile.
	\item Remove all geometry data (points, curves, loops, surface) from the generated geometry that lie above the surface line geometry.
	\item Reconstruct the surfaces, i.e. find which new surfaces are equal to the "old" surfaces as these were part of the subsoil profile. 
	Copy the soil, IsAquifer and WaterpressureInterpolationModel properties from the "old" surfaces when found else set default values for them
	(IsAquifer = false, WaterpressureInterpolationModel = Automatic, soil = filling material).
	\item Copy the pre-consolidation stresses from the original 2D subsoil profile to the new 2D profile.
	\item Rebox the geometry of the new 2D profile to set the proper limit values for that geometry.
	\item Update the surface line property of the geometry of the new 2D profile.
	\item Finally, round all coordinates in the geometry of the new 2D profile.
\end{itemize}

\subsection{Creating the new 2D Geometry}
\label{sec:Creating2DGeometry}
Creating the new 2D geometry involves:
\begin{itemize} 
	\item Clone the given original geometry.
	\item Perform all further actions on the cloned geometry.
	\item Check that the geometry contains at least 3 points and 3 curves.
	\item Ensure that the geometry has proper limits.
	\item Make sure that there is not already some sort of generation going on by checking that there are no newly effected points and/or curves.
	\item Adapt the geometry to the limits as defined by the surface line geometry. Do this by either cutting existing surfaces and/or extending 
	the geometry with new surfaces where needed.
	\item Add the surface line geometry (i.e. points and curves) to the geometry. Note that when needed extra curves can be added when the start-point and/or endpoint of the surface line are above the geometry.
	\item Add all the points and curves from the geometry as Newly Effected point/curves to the geometry.
	\item Remove all surfaces, loops, curves and points from the geometry.
	\item Regenerate the geometry (see \autoref{sec:Regenerating2DGeometry}).
	\item Delete all loose points and curves.
\end{itemize}

\subsection{Regenerating the new 2D Geometry}
\label{sec:Regenerating2DGeometry}
Regenerating the geometry involves:
\begin{itemize} 
	\item Locking the surfaces so asynchronous calls do not mess up the generation.
	\item Remove all double points and curves from the Newly Effected points/curves.
	\item Add the Newly Effected Points to Points.
	\item Add the Newly Effected Curves to Curves.
	\item Set up the curve-surfaces associations, i.e. whether a curve has a surface on the left and/or on the right of it. 
	Note that this is not required when the full combination procedure is used but it can be required when the "GenerateGeometry" procedure is used directly with an existing generated geometry.
	\item In a loop perform the next actions until the generation is ready (i.e. when all curves are handled in both forward and backward direction):
	\begin{itemize}
		\item Break up all curves at any intersection with any other curve even when they partially coincide whilst making sure the geometry stays correct whenever a curve needed to be split (see \autoref{sec:EnsuringCorrectGeometry}).
		\item Merge coinciding points that may be the result of the step above. Note that any obsolete curve (due to the merge) is removed too.
		\item Delete invalid and duplicated curves that may be the result of breaking the intersections.
		\item Initialize the geometryCurveForwardsIsUsed and geometryCurveBackwardsIsUsed dictionaries with false. 
		These dictionaries will be used to check if all curves are handled both in forward as well as backward direction. 
		When that's true then generation is finished.
		\item Start detecting surfaces using the Plaxis algorithm (see 
		\autoref{sec:DetectingSurfaces}).	
	\end{itemize}
	\item Clear the Newly Effected Points.
	\item Clear the Newly Effected Curves.
	\item Update the surface line property from the geometry.
\end{itemize}	

\subsection{Ensuring a correct geometry}
\label{sec:EnsuringCorrectGeometry}	
A correct geometry is obtained by:
\begin{itemize} 
	\item Make sure that all points that are used by Curves are in the Points list.
	\item Find all double points (by location) in Points and store these in a list.
	\item Replace all the double points as references in Curves and Newly Effected Curves.
	\item Remove all Curves and Newly Effected Curves that have no length (head-point = endpoint) from their lists and from all (inner and outer) loops (and thus surfaces). 
	\item Remove all invalid surfaces (i.e. a surface that has no area) that might be the result of curve deletion.
	\item Finally, remove all double points from Points and Newly Effected Points.  
\end{itemize}	

\subsection{Detecting surfaces}
\label{sec:DetectingSurfaces}	
Detecting surfaces involves:
\begin{itemize} 
	\item Create a list to store possible new loops.
	\item Create a list of direction curves. 
	A direction curve is a curve that holds the direction of the curve next to the curve itself. 
	It offers head and endpoint based on the direction, i.e. head-point becomes endpoint when the direction is backward.
	\item Start looping through the existing curves with curve 1 as current curve. This is the outer method loop to check all relevant curves which could become loops. 
	Note that all curves are handled twice: once with a forward direction and once with a backward direction.
	\item Create a new geometry loop and add the current curve. 
	\item Remember curve 1 and its direction so you can check whether the inner method loop (started next) is finished, i.e. when the next connected curve equals curve 1 and its direction.
	\item Start the inner method loop to gather all relevant curves for the geometry loop.    
	\item Find all curves connected to the endpoint of the current curve.
	\item If there is more than 1 connected curve, select the one that turns clockwise most and add it to the new geometry loop. 
	If there is only 1, just add that to the new geometry loop. 
	If there is no connected curve, something is wrong and an exception is raised.
	\item Replace the current curve and its direction by the just found connected curve and its direction.
	\item Continue the inner method loop with the adapted current curve to find the next connected one. 
	Keep doing this until the found next connected curve equals curve 1 which means the new geometry loop is ready. 
	Add that new loop to the new loop list and continue the outer method loop with the same curve but different direction or next curve in case both directions are done until all curves are checked for both directions.
	\item Now all possible new geometry loops are known and these are used to create surfaces (see \autoref{sec:CreatingSurfaces}).
\end{itemize}

\subsection{Creating surfaces}
\label{sec:CreatingSurfaces}	
When the list of possible new loops is known, the actual creation of the surfaces and its belonging  loops can begin. 
The given list of possible new loops can contain duplicates, anti clock wise oriented loops and or erroneous loops, all of which filtered out in the process:
\begin{itemize} 
	\item Start looping through all possible new loops.
	\item For each loop:
	\begin{itemize} 
		\item Check the validity of the loop (is it a continuous loop, does it have an area). 
		If it is invalid, ignore it.
		\item When the loop is clockwise and does not contain protruding curves that turn back on itself, a new surface with new loop as outer loop is created and added to the new surfaces list. 
		Else, ignore it.
		\item When this surface is not already part of the existing geometry so far (by checking if there is any existing surface that contains the same curves), it is added to the surfaces list of the geometry.
	\end{itemize}		
	\item Clear the SurfaceAtLeft/SurfaceAtRight status for all curves in the geometry.
	\item Start a new loop over all the new surfaces.
	\item For each new surface:
	\begin{itemize} 
		\item Assign the SurfaceAtLeft/SurfaceAtRight for all curves in the new surface. 
		This is required to make a regeneration process (as opposed to a generation process) possible as that relies on the existing surfaces being assigned to the existing curves. 
		\item Check for inner loops. See if any existing surface/outerloop is an inner loop to the new surface and add these to the new surface. See if the new surface is an inner loop to an existing surface in the geometry and if so at it as inner loop to that existing surface. 
	\end{itemize}
\end{itemize}
