Soil profiles and gridscd

class groundhog.general.soilprofile.SoilProfile(*args, **kwargs)

A SoilProfile object is a Pandas dataframe with specific functionality for geotechnical calculations. There is a column syntax requirement in which the columns with the top and bottom depth need to be defined for each layer. By default ‘Depth from [m]’ and ‘Depth to [m]’ are expected but this can be customised.

__init__(*args, **kwargs)

Overrides the init method of a dataframe to check the correctness of the layering and to set the depth column names.

adjust_layertransition(currentdepth, newdepth, tolerance=0.001)

Adjusts the depth of a layer transition.

Parameters:

• currentdepth – Current depth of the layer transition

• newdepth – Desired new depth of the layer transition

• tolerance – Offset above and below currentdepth in which a layer transition is sought (to cope with number precision issues)

applyfunction(function, resultkey, outputkey, parametermapping={}, **kwargs)

Applies a groundhog function to a soil profile. The function is applied to each row of the soilprofile. The result is stored in a column with name output. resultkey determines which key of the function output dictionary is used as the result.

The parameters of the function are mapped to columns of the soil profile using the parametermapping dictionary. The keys of this dictionary are the function arguments, the values are the corresponding columns of the soilprofile. For parameters with linear variation, this method only needs to be applied once and the soil parameter name (without from or to) needs to be supplied in the parametermapping dictionary.

Parameters:

• function – Function to be applied

• resultkey – Column name for the result (for parameters with linear variation, two result columns are created)

• outputkey – The key of the function output dictionary to be used for the result

• parametermapping – Dictionary mapping parameters of the function to column names

• applyatcenter – Boolean determining whether the function needs to be applied at the center of the layer for a linearly varying parameter. A single output column will then be returned (default=False).

• kwargs – Additional keyword arguments of the function which are not mapped to soil profile columns

Returns:

calculate_center(layercentercol='Depth center [m]')

Adds a column with the layer center depth to the soil profile :param layercentercol: Name of the column with the layer center :return: Adds a column with the layer center

calculate_layerthickness(layerthicknesscol='Layer thickness [m]')

Adds a column with the layer thickness to the soil profile :param layerthicknesscol: Name of the column with the layer thickness :return: Adds a column with the layer thickness

calculate_overburden(waterlevel=0, waterunitweight=10, initial_vertical_total_stress=0, totalunitweightcolumn='Total unit weight [kN/m3]', effectiveunitweightcolumn='Effective unit weight [kN/m3]', waterunitweightcolumn='Water unit weight [kN/m3]', totalverticalstresscolumn='Vertical total stress [kPa]', effectiveverticalstresscolumn='Vertical effective stress [kPa]', hydrostaticpressurecolumn='Hydrostatic pressure [kPa]')

Calculates the overburden pressure (total and effective) for a SoilProfile object. The SoilProfile object needs to contain a column with the total unit weight. By default, this is Total unit weight [kN/m3]. If the water level does not correspond with a layer interface, an additional layer interface is created. Total and effective unit weights are calculated for each layer and the method depth_integration is used to calculate the total vertical stress, effective vertical stress and hydrostatic pressure.

Note that vertical stress calculations in other units are possible, but the water unit weight then needs to be specified in consistent units.

An initial value can be added to the total vertical stress to simulate the effect of e.g. surcharging.

Parameters:

• waterlevel – Water level [m] (default 0m)

• waterunitweight – Unit weight of the pore water [kN/m3] (default=10kN/m3)

• initial_vertical_total_stress – Initial value of vertical total stress [kPa] (default=0kPa)

• totalunitweightcolumn – Column name containing total unit weights (default=’Total unit weight [kN/m3]’

• waterunitweightcolumn – Output column with the effective unit weight (default=’Effective unit weight [kN/m3]’)

• waterunitweightcolumn – Output column with the water unit weight (default=’Water unit weight [kN/m3]’)

• totalverticalstresscolumn – Total vertical stress column name (default=’Total vertical stress [kPa]’)

• effectiveverticalstresscolumn – Effective vertical stress column name (default=’Vertical effective stress [kPa]’)

• hydrostaticpressurecolumn – Hydrostatic pressure column name (default=’Hydrostatic pressure [kPa]’)

Returns:

Adds the column names from totalverticalstresscolumn, effectiveverticalstresscolumn and hydrostaticpressurecolumn to the SoilProfile object

calculate_parameter_center(parameter, suffix='center')

Calculates the value of a soil parameter at the center. The soil parameter needs to be a linearly varying numerical soil parameter. :param parameter: Numerical soil parameter for which the value at the center needs to be computed. :param suffix: Suffix to use instead of from or to :return: Adds an extra column with from or to in the column name replaced by the chosen suffix

check_linear_variation(parameter)

Check if a soil parameter varies linearly or not. :return: Boolean determining whether a soil parameter has a linear variation or not

check_profile()

Check if the SoilProfile meets the requirements for calculations

convert_depth_reference(newname='Depth', newunit='m', multiplier=1)

Converts the depth reference for a soil profile between one set of units (e.g. ft) to another (e.g. m) :param newname: New name for the depth reference (default=’Depth’) :param newunit: Name of the new unit (default=m) :param multiplier: Multiplier to go from old to new depth unit (e.g. 0.3 to go from ft to m) :return:

convert_depth_sign()

Inverts the sign of the depth from and depth to column. This function is useful when the profiles needs to be examined relative to LAT

convert_to_constant(parameter, rule='mean')

Converts a linearly varying soil parameter to a parameter with constant value. :param parameter: Soil parameter to convert. Specify Total unit weight [kN/m3] if the SoilProfile contains columns Total unit weight from [kN/m3] and Total unit weight to [kN/m3]. :param rule: Select from ['min', 'mean', 'max'] to convert the linear variation to a constant value (default=’mean’) :return: Creates a column for the soil parameter with constant value and removes the column with the linear variation

cut_profile(top_depth, bottom_depth)

Returns a deep copy of the SoilProfile between the specified bounds :param top_depth: Top depth for cutting :param bottom_depth: Bottom depth for cutting :return: Deep copy of the SoilProfile between the specified bounds

depth_integration(parameter, outputparameter, start_value=0)

Integrate a certain parameter vs depth (e.g. unit weight to obtain vertical stress) Note: This routine is only implemented for parameters with a constant value in the layer. :param parameter: Parameter to be integrated :param outputparameter: Name of the output parameter (with units) :param start_value: Value at the top of the profile (default=0) :return: Adds a column to the SoilProfile object for the integrated parameter

insert_layer_transition(depth)

Inserts a layer transition in the soil profile at a specific depth The profile layer is simply split and the properties of the given layer are assigned to the new layers above and below the transition. For linearly varying parameters, an interpolation is performed.

layer_transitions(include_top=False, include_bottom=False)

Returns a Numpy array with the layer transition depths. Use the booleans include_top and include_bottom to in/exclude the top and bottom of the profile

map_soilprofile(nodalcoords, target_depthkey='z [m]', keys_to_map=None, invert_sign=False, offset=0, include_layertransitions=False)

Maps the soilprofile to a grid. The depth coordinates to the grid are specified in a list or Numpy array (nodalcoords). The depth coordinates should be strictly ascending (no duplicates) and the minimum and maximum should be contained inside the soil profile bounds. Layer transitions can be included in the grid when include_layertransitions=True. All soil parameters are interpolated onto this grid. :param nodalcoords: List or Numpy array with the nodal coordinates of the grid :param target_depthkey: Name of the depth key in the resulting dataframe :param keys_to_map: List with the soilprofile keys to map :param invert_sign: Boolean determining whether to invert the sign after interpolation :param offset: Offset by which the depth is shifted (added to the depth after sign conversion) :param include_layertransitions: Boolean to determine whether the layer transitions needs to be included in the grid (default=False) :return: Returns a dataframe with the full grid with soil parameters

property max_depth

Returns the maximum depth of the soil profile

merge_layers(layer_ids, keep='top')

Merges two layers. Depending on the keep keyword, the top or bottom properties are retained for the merged layer

Parameters:

• layer_ids – List with the 2 IDs of the layers to be merged

• keep – String determining whether to retain the parameters of the top or bottom layer for the merged layer (select ‘top’ or ‘bottom’)

Returns:

Reduces the number of layers of the SoilProfile object

property min_depth

Returns the minimum depth of the soil profile

numerical_soil_parameters(condense_linear=True)

Returns a list of numerical soil parameters available in the soil profile. Numerical soil parameters have units between square brackets. Soil parameters with linear variations are returned as a single soil parameter when the boolean condense_linear is set to True :return: Returns a list with the numerical soil parameters in the SoilProfile

parameter_at_depth(depth, parameter, shallowest=True)

Calculates the value for one of the SoilProfile parameters at a selected depth :param depth: Selected depth [m] :param parameter: String or Numerical soil parameter (linear interpolation for linearly varying parameters) :param shallowest: Boolean determining whether at a layer interface, the shallowest value needs to be used (default=True). :return: The value of the parameter at the selected depth

plot_profile(parameters, soiltypecolumn='Soil type', **kwargs)

Generates a Plotly plot of the soil parameters vs depth. The panel on which the parameter is plotted is determined by how the parameters are passed to the function.

parameters=(('qc [MPa]',), ('Dr [%]',)) will plot cone resistance in panel 1 and relative density in panel 2

parameters=(('qc [MPa]', 'qt [MPa]'), ('Dr [%]')) will plot cone resistance and total cone resistance in panel 1 and relative density in panel 2

A column wihh the soil type is expected for the plotting of the log

Parameters:

• parameters – List of parameters tuples for plotting

• kwargs – Additional keyword arguments for the plot_with_log function in the general.plotting module

Returns:

Plotly plot with mini-log and parameter values

remove_parameter(parameter)

Removes a soil parameter from the dataframe :param parameter: Soil parameter to remove. For linear variations, simple use the expression parameter [unit]. The routine takes care of removing both the ‘to’ and ‘from’ columns :return: Removes the requested soil parameter from the SoilProfile objec

selection_soilparameter(parameter, depths, values, rule='mean', linearvariation=False)

Function for automatic selection of a soil parameters in the layers of a soil profile based an a list of provided values. The selection can either be done for a constant value in the layer or a linear variation over the layer. Selection of a minimum, mean or average trend can be performed using the rule keyword

Parameters:

• parameter – Name of the parameter being selected (including unit in square brackets)

• depths – Depths at which a measurement is available (list or Numpy array)

• values – Values corresponding to the given depths (list or Numpy array)

• rule – Which rule to use for the selection (select from min, mean and max

• linearvariation – Boolean determining whether a linear variation needs to happen over the layer or not

Returns:

Adds one (constant value) or two (linear variation) columns to the dataframe

set_position(easting, northing, elevation, srid=4326, datum='mLAT')

Sets the position of a soil profile top in a given coordinate system.

By default, srid 4326 is used which means easting is longitude and northing is latitude.

The elevation is referenced to a chart datum for which mLAT (Lowest Astronomical Tide) is the default.

Parameters:

• easting – X-coordinate of the CPT position

• northing – Y-coordinate of the CPT position

• elevation – Elevation of the CPT position

• srid – SRID of the coordinate system (see http://epsg.io)

• datum – Chart datum used for the elevation

Returns:

Sets the corresponding attributes of the `PCPTProcessing` object

shift_depths(offset)

Shifts all layer coordinates downward or upward, depending on the sign of the given offset. The offset is added to the given coordinates

soil_parameters(condense_linear=True)

Returns a list of soil parameters available in the soil profile. Soil parameters with linear variations are returned as a single soil parameter when the boolean condense_linear is set to True :return: Returns a list of the soil parameters in the SoilProfile

soilparameter_series(parameter)

Returns two lists (depths and corresponding parameter values) for plotting of a soil parameter vs depth. The routine first checks whether a valid parameter is provided. The lists are formatted such that variations at a layer interface are adequately plotted. :param parameter: A valid soil parameter with units :return: Two lists (depths and corresponding parameter values)

string_soil_parameters()

Returns a list of string soil parameters available in the soil profile. String soil parameters have no square brackets. :return: Returns a list with the string soil parameters in the SoilProfile

class groundhog.general.soilprofile.CalculationGrid(soilprofile, dz, custom_nodes=None, include_layertransitions=True)

A CalculationGrid is an object which consist of a dataframe with nodes .nodes and a dataframe with elements .elements. Properties of the soil profile are mapped to the nodes and the elements to allow subsequent calculation. At layer transition nodes, the properties of the layer below are always assigned to the node.

__init__(soilprofile, dz, custom_nodes=None, include_layertransitions=True)

Initializes the CalculationGrid object from a SoilProfile object. A nodes offset dz needs to be specified. Additional nodes are inserted at layer transitions by default (include_layertransitions=True). The user can also specify a NumPy array with custom_nodes (None by default). After initialization, the dataframes of nodal and elemental information are created. For properties varying linearly across a layer, the value of the property at the element center is also calculated and is given the name of the parameter (without from and to).

set_elements()

Create a dataframe with elements. Each element has a top and bottom node. The soil property value at bottom and top are calculated, as well as the values at the center of the element.

soilparameter_series(parameter, ignore_linearvariation=False)

Returns two lists (depths and corresponding parameter values) for plotting of a soil parameter vs depth. The routine first checks whether a valid parameter is provided. The lists are formatted such that variations at a layer interface are adequately plotted. :param parameter: A valid soil parameter with units :param ignore_linearvariation: Boolean determining if linear variations need to be ignored :return: Two lists (depths and corresponding parameter values)