{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "f5299ef8",
   "metadata": {},
   "source": [
    "# Tutorial - Axial pile capacity calculation according to API RP2 GEO with groundhog\n",
    "\n",
    "At the request of users, a routine for axial capacity is developed within groundhog.\n",
    "\n",
    "The pile capacity class ``AxCapCalculation`` develops a workflow in which the unit skin friction methods and unit end bearing methods are introduced into a ``SoilProfile`` object.\n",
    "\n",
    "A check is then performed to assess whether the necessary soil parameters are defined in the ``SoilProfile``. If all necessary parameters are available, a calculation grid is defined and the unit skin friction and unit end bearing calculations are calculated. This notebook outlines the different components of the calculation for the API RP2 GEO Main Text method."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "77957da6",
   "metadata": {},
   "source": [
    "## Library imports\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8c22a2ac",
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1bc9aa18",
   "metadata": {},
   "outputs": [],
   "source": [
    "import plotly.io as pio\n",
    "pio.templates.default = 'plotly_white'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "048eba65",
   "metadata": {},
   "outputs": [],
   "source": [
    "from groundhog.general.soilprofile import SoilProfile\n",
    "from groundhog.general.plotting import LogPlot"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cc9955d2",
   "metadata": {},
   "source": [
    "## Preparing a ``groundhog`` ``SoilProfile`` object for axial capacity analysis\n",
    "\n",
    "### Definition of methods and soil parameters in ``SoilProfile``\n",
    "\n",
    "For each layer in the ``SoilProfile``, the unit skin friction and unit end bearing need to be set. Each methods has associated required parameters. The presence of these parameters can be checked before starting the calculation.\n",
    "\n",
    "First, a basic soil profile with three layers is defined:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e0d6d987",
   "metadata": {},
   "outputs": [],
   "source": [
    "sp = SoilProfile({\n",
    "    'Depth from [m]': [0, 5, 10],\n",
    "    'Depth to [m]': [5, 10, 20],\n",
    "    'Soil type': ['SAND', 'CLAY', 'SAND'],\n",
    "    'Total unit weight [kN/m3]': [20, 18, 20]\n",
    "})\n",
    "sp"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2988b860",
   "metadata": {},
   "source": [
    "Next, the calculation methods for unit skin friction and unit end bearing are specified in the columns ``Unit skin friction`` and ``Unit end bearing``."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "56f8d1ba",
   "metadata": {},
   "outputs": [],
   "source": [
    "sp['Unit skin friction'] = ['API RP2 GEO Sand', 'API RP2 GEO Clay', 'API RP2 GEO Sand']\n",
    "sp['Unit end bearing'] = ['API RP2 GEO Sand', 'API RP2 GEO Clay', 'API RP2 GEO Sand']\n",
    "sp"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "097b4d06",
   "metadata": {},
   "source": [
    "### Overburden calculation\n",
    "\n",
    "As several method require the vertical effective stress as an input, the stresses can be calculated using the ``calculate_overburden`` method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e28b4306",
   "metadata": {},
   "outputs": [],
   "source": [
    "sp.calculate_overburden()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1dd1c453",
   "metadata": {},
   "source": [
    "The vertical effective stress profile can be plotted:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "59a5e900",
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "stress_plot = LogPlot(sp, no_panels=1, fillcolordict={'SAND': 'yellow', 'CLAY': 'brown'})\n",
    "stress_plot.add_trace(\n",
    "    x=sp.soilparameter_series('Vertical effective stress [kPa]')[1],\n",
    "    z=sp.soilparameter_series('Vertical effective stress [kPa]')[0],\n",
    "    name=r'$ \\sigma_{v0}^{\\prime} $', showlegend=False, panel_no=1)\n",
    "stress_plot.set_xaxis(title=r'$ \\sigma_{v0}^{\\prime} \\ \\text{[kPa]} $', panel_no=1)\n",
    "stress_plot.set_zaxis(title=r'$ z \\ \\text{[m]} $', range=(20, 0))\n",
    "stress_plot.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dc6f0ac8",
   "metadata": {},
   "source": [
    "## Axial pile capacity calculation setup\n",
    "\n",
    "### Creating the calculation object\n",
    "\n",
    "An axial capacity calculation can be set up based on the soil profile. The ``AxcapCalculation`` class contains the necessary functionality."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3326adcf",
   "metadata": {},
   "outputs": [],
   "source": [
    "from groundhog.deepfoundations.axialcapacity.axcap import AxCapCalculation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b40f0fc8",
   "metadata": {},
   "outputs": [],
   "source": [
    "calc = AxCapCalculation(sp)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0508cbf5",
   "metadata": {},
   "source": [
    "### Checking of presence of require soil parameters\n",
    "\n",
    "The presence of the required input to unit skin friction and unit end bearing calculations can be checked. Note that both numerical and string soil parameters need to be checked:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e31ea761",
   "metadata": {},
   "outputs": [],
   "source": [
    "from groundhog.general.parameter_mapping import SOIL_PARAMETER_MAPPING, reverse_dict\n",
    "from groundhog.deepfoundations.axialcapacity.skinfriction import SKINFRICTION_PARAMETERS, SKINFRICTION_METHODS\n",
    "from groundhog.deepfoundations.axialcapacity.endbearing import ENDBEARING_PARAMETERS, ENDBEARING_METHODS"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4f3ba2e0",
   "metadata": {},
   "source": [
    "``groundhog`` has a standard mapping for soil parameters, which defines the mapping from column headers in a Pandas dataframe to ``groundhog`` function variables. Column headers must conform to this naming."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "39c6262c",
   "metadata": {},
   "outputs": [],
   "source": [
    "SOIL_PARAMETER_MAPPING"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7ba53be4",
   "metadata": {},
   "source": [
    "The necessary parameters for skin friction calculation can be printed. In v0.9.0, only the API RP2 GEO methods are defined with their associated parameters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2801771b",
   "metadata": {},
   "outputs": [],
   "source": [
    "SKINFRICTION_PARAMETERS"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0f11246b",
   "metadata": {},
   "source": [
    "With the method ``check_methods``, the presence of the parameters can be checked. At this point, the parameters are not yet defined so the method will return a message that the required parameters are not found."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ace9bbf9",
   "metadata": {},
   "outputs": [],
   "source": [
    "calc.check_methods()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "75566c90",
   "metadata": {},
   "source": [
    "The required soil parameters can be defined. Example parameters are defined below. The documentation of the unit skin friction and unit end bearing methods can be checked in the ``groundhog`` documentation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e259d473",
   "metadata": {},
   "outputs": [],
   "source": [
    "calc.sp['API soil description'] = ['Sand-silt', None, 'Sand']\n",
    "calc.sp['API relative density description'] = ['Medium dense', None, 'Dense']\n",
    "calc.sp['Undrained shear strength from [kPa]'] = [np.nan, 100, np.nan]\n",
    "calc.sp['Undrained shear strength to [kPa]'] = [np.nan, 150, np.nan]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "115b7810",
   "metadata": {},
   "source": [
    "When re-running the ``check_methods`` no messages are returned. But the attribute ``checked`` is now ``True``."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cb670c65",
   "metadata": {},
   "outputs": [],
   "source": [
    "calc.check_methods()\n",
    "calc.checked"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "480fbcc3",
   "metadata": {},
   "source": [
    "## Gridding for axial capacity calculation"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ac7531c3",
   "metadata": {},
   "source": [
    "A calculation grid can be created based on the soil profile with a spacing of 1m."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ea110216",
   "metadata": {},
   "outputs": [],
   "source": [
    "calc.create_grid(dz=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3f785cb9",
   "metadata": {},
   "source": [
    "The grid has a ``nodes`` and ``elements`` attribute where the former contains the nodal coordinates and the associated parameter values at the nodes. The latter contains the element definition with the parameter values at the center of the element."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5e7c53b3",
   "metadata": {},
   "outputs": [],
   "source": [
    "calc.grid.nodes.head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5bcaf639",
   "metadata": {},
   "outputs": [],
   "source": [
    "calc.grid.elements.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4e7769e3",
   "metadata": {},
   "source": [
    "The parameters in the grid can be prepared for plotting by applying the ``soilparameter_series`` with the name of the parameter under consideration. The x- and z-values can be defined based on the parameter name."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3d29f620",
   "metadata": {},
   "outputs": [],
   "source": [
    "su_z, su_x = calc.grid.soilparameter_series('Undrained shear strength [kPa]')\n",
    "sigmav_z, sigmav_x = calc.grid.soilparameter_series('Vertical effective stress [kPa]')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "29f7e0f0",
   "metadata": {},
   "outputs": [],
   "source": [
    "parameter_plot = LogPlot(calc.sp, no_panels=2, fillcolordict={'SAND': 'yellow', 'CLAY': 'brown'})\n",
    "\n",
    "parameter_plot.add_trace(x=su_x, z=su_z, showlegend=False, mode='lines',name='Su', panel_no=1)\n",
    "parameter_plot.add_trace(x=sigmav_x, z=sigmav_z, showlegend=True, mode='lines',name='With linear', panel_no=2)\n",
    "\n",
    "parameter_plot.set_xaxis(title=r'$ \\sigma_{vo}^{\\prime} \\ \\text{[kPa]} $', panel_no=2, range=(0, sigmav_x.max()))\n",
    "parameter_plot.set_xaxis(title=r'$ S_u \\ \\text{[kPa]} $', panel_no=1, range=(0, 400))\n",
    "parameter_plot.set_zaxis(title=r'$ z \\ \\text{[m]}$')\n",
    "parameter_plot.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "549b94d4",
   "metadata": {},
   "source": [
    "## Calculation of unit skin friction and unit end bearing\n",
    "\n",
    "Unit skin friction and unit end bearing can be calculated by running the functions for the selected methods at each element.\n",
    "\n",
    "Note that the unit skin friction distribution may be depth-dependent, so at this stage, the pile penetration will need to be introduced.\n",
    "\n",
    "### Setting the pile penetration\n",
    "\n",
    "The pile penetration can be set with the ``set_pilepenetration`` method. In this example, a pile penetration of 18m is selected."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b8432b63",
   "metadata": {},
   "outputs": [],
   "source": [
    "calc.set_pilepenetration(18)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1d55c0d0",
   "metadata": {},
   "source": [
    "### Calculation of unit skin friction\n",
    "\n",
    "For the calculation of unit skin friction, the equation for the selected method is applied for each element."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "21003bed",
   "metadata": {},
   "outputs": [],
   "source": [
    "calc.calculate_unitskinfriction()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6a42597b",
   "metadata": {},
   "source": [
    "### Calculation of unit end bearing\n",
    "\n",
    "Similarly, the unit end bearing can be calculated:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1bed3419",
   "metadata": {},
   "outputs": [],
   "source": [
    "calc.calculate_unitendbearing()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bdfe66ed",
   "metadata": {},
   "source": [
    "### Unit skin friction and unit end bearing visualisation\n",
    "\n",
    "The unit skin friction and unit end bearing profile can be visualised with the ``groundhog`` ``LogPlot``."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "66a87954",
   "metadata": {},
   "outputs": [],
   "source": [
    "z_fs, x_fs = calc.output.soilparameter_series('Unit skin friction outside compression [kPa]')\n",
    "z_qb, x_qb = calc.output.soilparameter_series('Unit end bearing plugged [kPa]')\n",
    "\n",
    "fs_qb_plot = LogPlot(calc.output, no_panels=2, fillcolordict={'SAND': 'yellow', 'CLAY': 'brown'})\n",
    "\n",
    "fs_qb_plot.add_trace(x=x_fs, z=z_fs, showlegend=False, mode='lines',name='fs comp', panel_no=1)\n",
    "fs_qb_plot.add_trace(x=x_qb, z=z_qb, showlegend=False, mode='lines',name='qb', panel_no=2)\n",
    "\n",
    "fs_qb_plot.set_xaxis(title=r'$ q_b \\ \\text{[kPa]} $', panel_no=2, range=(0, x_qb.max()))\n",
    "fs_qb_plot.set_xaxis(title=r'$ f_s \\ \\text{[kPa]} $', panel_no=1, range=(0, x_fs.max()))\n",
    "fs_qb_plot.set_zaxis(title=r'$ z \\ \\text{[m]}$')\n",
    "fs_qb_plot.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fc7ca667",
   "metadata": {},
   "source": [
    "## Integration of unit skin friction and unit end bearing\n",
    "\n",
    "Unit skin friction can be integrated over the annulus of the pile. Four modes are discerned:\n",
    "\n",
    "   - Plugged compression: Outside skin friction and end bearing over the full diameter of the pile\n",
    "   - Plugged tension: Outside skin friction in tension + weight of the pile material and/or internal soil plug\n",
    "   - Coring compression: Outside skin friction + inside skin friction + annular end bearing\n",
    "   - Coring tension: Outside skin friction in tension + inside skin friction in tension\n",
    "   \n",
    "The pile circumference and base cross-sectional area need to be known. Because pile shapes and sizes may differ, the weight of the pile and/or internal soil plug is excluded from the assessment. Calculating this component with a separate calculation is straightforward.\n",
    "\n",
    "In this example, a tubular open-ended pile with 2.48m outer diameter and 50mm wall thickness is taken."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a6aa0054",
   "metadata": {},
   "outputs": [],
   "source": [
    "calc.calculate_pilecapacity(\n",
    "    circumference=np.pi * 2.48, base_area=0.25 * np.pi * 2.48 ** 2,\n",
    "    internal_circumference=np.pi * 2.38, annulus_area=0.25 * np.pi * (2.48 ** 2 - 2.38 ** 2))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4f807dbb",
   "metadata": {},
   "outputs": [],
   "source": [
    "calc.output.tail()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "809018b7",
   "metadata": {},
   "source": [
    "### Results for the final penetration\n",
    "\n",
    "As unit skin friction profiles can be penetration-dependent, the plot of unit skin friction $ f_s $ is only valid for the selected final pile penetration.\n",
    "\n",
    "The profiles of unit skin friction $ f_s $, unit end bearing $ q_b $ and integrated shaft resistance in compression and tension over the inside and outside of the pile are plotted as well as the plugged and unplugged (coring) end bearing."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e32fbb21",
   "metadata": {},
   "outputs": [],
   "source": [
    "calc.plot_single_penetration()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0b3106bf",
   "metadata": {},
   "source": [
    "Numerical values of the results are available in the ``result`` attribute. These values are valid for the final pile penetration."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e1bd24bf",
   "metadata": {},
   "outputs": [],
   "source": [
    "calc.result"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "340609be",
   "metadata": {},
   "source": [
    "### Results for all penetrations\n",
    "\n",
    "The calculation of axial pile capacity needs to be repeated for every pile penetration for pile sizing as unit skin friction and unit end bearing can be depth-dependent (e.g. due to friction fatigue)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9b5dbf68",
   "metadata": {},
   "outputs": [],
   "source": [
    "calc.calculate_capacity_profile(\n",
    "    circumference=np.pi * 2.48, base_area=0.25 * np.pi * 2.48 ** 2,\n",
    "    internal_circumference=np.pi * 2.38, annulus_area=0.25 * np.pi * (2.48 ** 2 - 2.38 ** 2),\n",
    "    pile_weight_permeter=0.25 * np.pi * (2.48 ** 2 - 2.38 ** 2) * 68.5,\n",
    "    soilplug_weight_permeter=0.25 * np.pi * 2.38 ** 2 * 10)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a22cae7a",
   "metadata": {},
   "source": [
    "The results can be visualised. The leftmost panel shows the shaft resistance in compression and tension for plugged (only outside) and coring (inside and outside) conditions. The coring and plugged base resistance are shown in the middle panel. In the right-most panel, the compression and tension resistance for plugged and coring conditions are shown. Depending on the relative magnitude of internal shaft resistance vs end bearing on the plug, the calculation selects whether plugged (internal shaft resistance > end bearing on soil plug) or coring (internal shaft resistance < end bearing on soil plug) conditions are expected."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "71630010",
   "metadata": {},
   "outputs": [],
   "source": [
    "calc.plot_all_penetrations()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e019eea9",
   "metadata": {},
   "source": [
    "The results are shown in a dataframe which can be exported to csv or Excel."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "82bd7eff",
   "metadata": {},
   "outputs": [],
   "source": [
    "calc.capacity_profile.head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1cb5375d",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "hide_input": false,
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.9"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": true,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {
    "height": "calc(100% - 180px)",
    "left": "10px",
    "top": "150px",
    "width": "343.825px"
   },
   "toc_section_display": true,
   "toc_window_display": true
  },
  "varInspector": {
   "cols": {
    "lenName": 16,
    "lenType": 16,
    "lenVar": 40
   },
   "kernels_config": {
    "python": {
     "delete_cmd_postfix": "",
     "delete_cmd_prefix": "del ",
     "library": "var_list.py",
     "varRefreshCmd": "print(var_dic_list())"
    },
    "r": {
     "delete_cmd_postfix": ") ",
     "delete_cmd_prefix": "rm(",
     "library": "var_list.r",
     "varRefreshCmd": "cat(var_dic_list()) "
    }
   },
   "types_to_exclude": [
    "module",
    "function",
    "builtin_function_or_method",
    "instance",
    "_Feature"
   ],
   "window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}