Merge pull request #23 from TchilDill/extras-doc-unit-testing-and-more

0.4.0

Author: TchilDill

CHANGELOG.md

@@ -8,8 +8,19 @@ and this project adheres to [Semantic Versioning](http://semver.org/),
 and [PEP 440](https://www.python.org/dev/peps/pep-0440/).
 
 
-## [0.4.0] - 2023-XX-XX (not released yet) 
-- *blank*
+## [0.4.0] - 2023-07-30 (not released yet) 
+- Updates in documentation
+- new methods available for `openpile.analyze.Result` class:
+  - new method `winkler()` replacing `simple_winkler_analysis()`, the use of the latter triggers a deprecation warning when used.
+  - new method `beam()` replacing `simple_beam_analysis()`, the use of the latter triggers a deprecation warning when used.
+  - new method `openpile.analyze.details()` that provides summary of an `AnalyzeResult` object.
+- new methods available for `openpile.construct.Model` class:
+  - `openpile.construct.Model.get_py_springs()`
+  - `openpile.construct.Model.get_mt_springs()`
+  - `openpile.construct.Model.get_Hb_spring()`
+  - `openpile.construct.Model.get_Mb_spring()`
+- new feature which allow user to enter a function in place of a float for springs multipliers when creating `SoilModel` objects. the function must take as input a PositiveFloat representing the depth below ground level, and as output the multiplier that shall be used by the soil spring for this depth.
+- new `openpile.utils.multipliers` module that stores validated functions for use in multipliers in SoilModels objects.
 
 ## [0.3.3] - 2023-05-19 
 - fix error in Dunkirk_sand rotational springs

README.md

@@ -5,7 +5,7 @@ Geotechnical super-toolbox for pile-related calculations.
 <!-- [![Python Support](https://img.shields.io/pypi/pyversions/openpile.svg)](https://pypi.org/project/openpile/) -->
 [![License: LGPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
 [![Open Source? Yes!](https://badgen.net/badge/Open%20Source%20%3F/Yes%21/blue?icon=github)](https://github.com/Naereen/badges/)
-[![Downloads](https://static.pepy.tech/badge/openpile)](https://pepy.tech/project/openpile)
+[![Downloads](https://static.pepy.tech/badge/openpile/month)](https://pepy.tech/project/openpile)
 
 ![Tests](https://github.com/TchilDill/openpile/actions/workflows/Test.yml/badge.svg) 
 [![Documentation Status](https://readthedocs.org/projects/openpile/badge/?version=latest)](https://openpile.readthedocs.io/en/latest/?badge=latest)

docs/source/API.rst

@@ -1,3 +1,6 @@
+
+.. _ApplicationProgrammingInterface:
+
 ---
 API
 ---
@@ -12,9 +15,9 @@ API
                       LateralModel, AxialModel, py_spring_fct, mt_spring_fct, Hb_spring_fct, 
                       Mb_spring_fct, spring_signature
 
-.. automodule:: openpile.analyses
+.. automodule:: openpile.analyze
     :members: 
-    :exclude-members: PydanticConfig, structural_forces_to_df, disp_to_df, Result
+    :exclude-members: simple_winkler_analysis, simple_beam_analysis, PydanticConfig, structural_forces_to_df, springs_mob_to_df, reaction_forces_to_df, disp_to_df, AnalyzeResult
 
 
 `utils` module
@@ -32,7 +35,7 @@ API
 
 .. automodule:: openpile.utils.tz_curves
     :members:
-    :exclude-members: random
+    :exclude-members: random, kraft_modification
 
 
 .. automodule:: openpile.utils.qz_curves
@@ -43,13 +46,7 @@ API
 The `Result` class
 ==================
 
-.. autoclass:: openpile.analyses.Result
+.. autoclass:: openpile.analyze.AnalyzeResult
     :members:
-    :exclude-members: name, displacements, forces, Config, __init__
-
-    Usage
-    -----
-
-    The `Result` class is created by any analyses from the :py:mod:`openpile.analyses` module.
+    :exclude-members: Config, __init__
 
-    As such the user can use the following properties and/or methods for any return values of an analysis. 

docs/source/_static/plots/API_Qz_curve.png

@@ -0,0 +1,61 @@
+Axial soil models
+=================
+
+The following axial models are included in openpile. 
+
+* API sand
+* API Clay
+
+
+API model
+---------
+
+The axial  model calculates skin friction along the pile and end-bearing at pile tip.
+
+OpenPile's use of this model is done by calling the following class in a layer:
+
+* in coarse-grained materials, :py:class:`openpile.soilmodels.API_ax_sand`
+* in fine-grained materials, :py:class:`openpile.soilmodels.API_ax_clay`
+
+This soil model then provides soil springs as given by the function(s) below and depending on the type of material:
+
+* :py:func:`openpile.utils.tz_curves.api_sand`
+* :py:func:`openpile.utils.qz_curves.api_sand`
+* :py:func:`openpile.utils.tz_curves.api_clay`
+* :py:func:`openpile.utils.qz_curves.api_clay`
+
+
+Distributed springs - t-z curves
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The backbone curve is computed via the piecewise formulation 
+by [API2000]_ or through 
+Kraft's formulation that captures small-strain 
+characteristics of the soil [KrRK81]_ in the backbone curve.
+
+.. note::
+    Kraft's formulation is accessed by the user by stipulating the small-strain shear 
+    stiffness of the soil, :math:`G_0`
+
+**API Sand**
+
+*pending..*
+
+**API Clay**
+
+*pending..*
+
+Base spring - Q-z curve
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The maximum resistance is calculated as follows:
+
+* API clay: :math:`Q_{max} = 9 S_u`
+  where :math:`S_u` is the clay undrained shear strength.
+* API sand: :math:`Q_{max} = N_q \sigma^\prime_v`
+  where :math:`\sigma^\prime_v` is the overburden effective stress and :math:`N_q` is 
+  the end-bearing factor depending on the interface friction angle :math:`\delta = \phi - 5` given in [API2000]_.
+
+
+The backbone curve is computed via the piecewise formulation 
+by [API2000]_.

docs/source/_static/usage/analyses_plots/main_results_plot.png

@@ -3,7 +3,9 @@ Background and Theory
 ---------------------
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
    :caption: Contents:
 
-   PYmodels
+   introsoilmodels
+   lateralsoilmodels
+   axialsoilmodels

docs/source/_static/usage/pycurves/api_sand_example_build.png

@@ -0,0 +1,49 @@
+
+Usage
+=====
+
+The function :py:func:`openpile.utils.py_curves.[<py spring>]` generates the lateral springs (or p-y curve/spring) 
+for the relevant soil model. Similar modules exist for other types of springs:
+
+* rotational springs (found in :py:mod:`openpile.utils.mt_curves`)
+* axial springs (found in :py:mod:`openpile.utils.tz_curves`)
+* base lateral spring (found in :py:mod:`openpile.utils.Hb_curves`)
+* base rotational spring (found in :py:mod:`openpile.utils.Mb_curves`)
+* base axial spring (found in :py:mod:`openpile.utils.qz_curves`)
+
+
+Furthermore, the user can include the those springs discussed in a soil profile's :py:class:`openpile.construct.Layer` 
+by calling a soil mode, found in :py:class:`openpile.soilmodels.[<soil model>]` 
+
+The rest of the below documentation discusses the soil models available to the user, 
+the theory behind and calculations. 
+Please refer to the :ref:`ApplicationProgrammingInterface` for more details and :ref:`usage` for more practical information.
+
+
+.. rubric:: References 
+
+.. [MuOn83] Murchison, J.M., and O'Neill, M.,W., 1983. *An Evaluation of p-y Relationships 
+    in Sands.* Rserach Report No. GT.DF02-83, Department of Civil Engineering, 
+    University of Houston, Houston, Texas, May, 1983.
+.. [MuOn84] Murchison, J.M., and O'Neill, M.,W., 1984. *Evaluation of p-y relationships 
+    in cohesionless soils.* In Proceedings of Analysis and Design of Pile Foundations, 
+    San Francisco, October 1-5, pp. 174-191.
+.. [DNV-RP-C212] DNVGL RP-C212. *Recommended Practice, Geotechnical design*.
+    Edition 2019-09 - Amended 2021-09.
+.. [API2000] API, December 2000. *Recommended Practice for Planning, Designing, and Constructing 
+    Fixed Offshore Platforms - Working Stress Design (RP 2A-WSD)*, Twenty-First Edition.
+.. [Matl70] Matlock, H. (1970). *Correlations for Design of Laterally Loaded Piles in Soft Clay*. 
+    Offshore Technology Conference Proceedings, Paper No. OTC 1204, Houston, Texas. 
+.. [BaCA06] Battacharya,  S.,  Carrington,  T.  M.  and  Aldridge,  T.  R.  (2006),  
+    *Design  of  FPSO  Piles  against  Storm  Loading*. Proceedings Annual Offshore Technology 
+    Conference, OTC17861, Houston, Texas, May, 2006.
+.. [KrRK81] Kraft, L.M., Ray, R.P., and Kagawa, T. (1981). *Theoretical t-z curves*. 
+    Journal of the Geotechnical Engineering Division, ASCE, Vol. 107, No. GT11, pp. 1543-1561.
+.. [BHBG20] Byrne, B. W., Houlsby, G. T., Burd, H. J., Gavin, K. G., Igoe, D. J. P., 
+    Jardine, R. J., Martin, C. M., McAdam, R. A., Potts, D. M., Taborda, D. M. G. & Zdravkovic ́, L. (2020). 
+    PISA design model for monopiles for offshore wind turbines: application 
+    to a stiff glacial clay till. Géotechnique, https://doi.org/10.1680/ jgeot.18.P.255.
+.. [BTZA20] Burd, H. J., Taborda, D. M. G., Zdravkovic ́, L., Abadie, C. N., Byrne, B. W., 
+    Houlsby, G. T., Gavin, K. G., Igoe, D. J. P., Jardine, R. J., Martin, C. M., McAdam, R. A., 
+    Pedro, A. M. G. & Potts, D. M. (2020). PISA design model for monopiles for offshore wind 
+    turbines: application to a marine sand. Géotechnique, https://doi.org/10.1680/jgeot.18.P.277.

docs/source/_static/validation/CowdenClay_D1_D2.png

@@ -1,54 +1,37 @@
-PY soil models
-==============
+Lateral soil models
+===================
 
-The following PY models are included in openpile. 
-
-* :ref:`API-sand` 
-* :ref:`API-clay` 
-
-The function :py:func:`openpile.utils.py_curves.[<PY soil model>]` generates the p-y curve for 
-the relevant PY soil model.
-
-Furthermore, the user can include the PY soil models discussed here in a soil profile's :py:class:`openpile.construct.Layer` 
-by calling the class :py:class:`openpile.soilmodels.[<PY soil model>]` 
-
-This part of the documentation discusses the theory and calculations. 
-Please refer to the API or Usage sections for more practical information.
-
-.. rubric:: References 
-
-.. [MuOn83] Murchison, J.M., and O'Neill, M.,W., 1983. *An Evaluation of p-y Relationships 
-    in Sands.* Rserach Report No. GT.DF02-83, Department of Civil Engineering, 
-    University of Houston, Houston, Texas, May, 1983.
-.. [MuOn84] Murchison, J.M., and O'Neill, M.,W., 1984. *Evaluation of p-y relationships 
-    in cohesionless soils.* In Proceedings of Analysis and Design of Pile Foundations, 
-    San Francisco, October 1-5, pp. 174-191. 
-.. [DNV-RP-C212] DNVGL RP-C212. *Recommended Practice, Geotechnical design*.
-    Edition 2019-09 - Amended 2021-09.
-.. [API2GEO-2011] API, April 2011. *Geotechnical and Foundation Design Considerations, 
-    ANSI/API Recommended Practice 2GEO*, First Edition, American Petroleum Institute, p. 103
-.. [Matl70] Matlock, H. (1970). *Correlations for Design of Laterally Loaded Piles in Soft Clay*. 
-    Offshore Technology Conference Proceedings, Paper No. OTC 1204, Houston, Texas. 
-.. [BaCA06] Battacharya,  S.,  Carrington,  T.  M.  and  Aldridge,  T.  R.  (2006),  
-    *Design  of  FPSO  Piles  against  Storm  Loading*. Proceedings Annual Offshore Technology 
-    Conference, OTC17861, Houston, Texas, May, 2006. 
+The following lateral models are included in openpile. 
 
+* :ref:`API-lat-sand`
+* :ref:`API-lat-clay`
+* :ref:`Dunkirk-sand`
+* :ref:`Cowden-clay`
 
 .. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-.. _API-sand:
+.. _API-lat-sand:
 
 API sand
 --------
 
-The p-y formulation called API sand is based on the publication by 
+The API sand soil model is based on the publication by 
 O'neill and Murchison, preceded by work from Reese, L.C. and others (
 see [MuOn83]_ and [MuOn84]_). 
 
+OpenPile's use of this model is done by calling the following class in a layer:
+
+* :py:class:`openpile.soilmodels.API_sand`
+
+This soil model provides soil springs as given by the function(s):
+
+* :py:func:`openpile.utils.py_curves.api_sand`
+
+
 p-y formulation
 ^^^^^^^^^^^^^^^
 
 The API sand formulation is presented in both the API and DNVGL standards,
-see, [DNV-RP-C212]_ and [API2GEO-2011]_.
+see, [DNV-RP-C212]_ and [API2000]_.
 
 Granular soils are modelled by the sand p-y model as described 
 with the following backbone formula:
@@ -136,17 +119,24 @@ where:
 * :math:`\sigma^{\prime}` is the vertical effective stress
 
 .. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-.. _API-clay:
+.. _API-lat-clay:
 
 API clay
 --------
 
-The p-y formulation called API clay is based on the work conducted by Matlock (1970) (see [Matl70]_).  
+The lateral soil model called API clay is based on the work conducted by Matlock (1970) (see [Matl70]_).  
+
+OpenPile's use of this model is done by calling the following class in a layer:
+
+* :py:class:`openpile.soilmodels.API_clay`
+
+This soil model provides soil springs as given by the function(s):
+
+* :py:func:`openpile.utils.py_curves.api_clay`
 
-The API clay formulation is presented in both the API and DNVGL standards,
-see [DNV-RP-C212]_ and [API2GEO-2011]_. 
+The p-y clay formulation is presented in both the API and DNVGL standards,
+see [DNV-RP-C212]_ and [API2000]_. 
 
-The below section describes how this model is formulated and computed by openpile. 
 
 .. note::
     From an undrained shear strength of 96 kPa (assumed as the threshold at which a clay is considered stiff), 
@@ -277,3 +267,42 @@ the p-y curve can be generated according to:
     \end{cases}  
 
 
+.. _Dunkirk-sand:
+
+Dunkirk-sand (PISA model)
+-------------------------
+
+This soil model was formulated as part of the Joint Industry Project PISA, that focused on formulating soil springs for large diameter monopiles as found in the offshore wind industry. 
+This resulted in soil springs formulated in a normalized space based on a conic function backbone curve and the few following soil parameters, 
+(i) undrained shear strength and (ii) small-strain shear stiffness. 
+This standard model only account for monotonic reaction curves and as usual, it reflects the site conditions of the site the curves were calibrated from, a site in Dunkirk, France where dense sand is found. 
+More details can be found in [BTZA20]_.
+
+The model is validated in the below figure by performing a benchmark of OpenPile
+against the source material, [BTZA20]_. OpenPile shows some differences in result for high lateral load. 
+This is due to the lack of clearer guidance in deriving `G0` in the source material.
+
+.. figure:: _static/validation/GDSM_D2t.png
+    :width: 80%
+
+    Validation against pile D2t documented in [BTZA20]_.
+
+.. _Cowden-clay:
+
+Cowden-clay (PISA model)
+------------------------
+
+This soil model was formulated as part of the Joint Industry Project PISA, that focused on formulating soil springs for large diameter monopiles as found in the offshore wind industry. 
+This resulted in soil springs formulated in a normalized space based on a conic function backbone curve and the few following soil parameters, 
+(i) undrained shear strength and (ii) small-strain shear stiffness. 
+This standard model only account for monotonic reaction curves and as usual, it reflects the site conditions of the site the curves were calibrated from, a site in Cowden, England where overconsolidated glacial till is found. 
+More details can be found in [BHBG20]_.
+
+The model is validated in the below figure by performing a benchmark of OpenPile
+against the source material, [BHBG20]_.
+
+.. figure:: _static/validation/CowdenClay_D1_D2.png
+    :width: 80%
+
+    Validation against piles D1 and D2 documented in [BHBG20]_.
+

docs/source/_static/validation/GDSM_D2t.png

@@ -1,10 +1,13 @@
+
+.. _usage:
+
 -----
 Usage
 -----
 
 The package allows a quick input by the user (given in this section) and quick calculation. 
 
-Jupyter Notebooks/IPython are recommended platforms to learn how to use openpile as it provides 
+Jupyter Notebooks/IPython are recommended platforms to use openpile as it provides 
 an interactive experience. 
 
 .. _Ex1-create_a_pile:
@@ -118,7 +121,7 @@ API sand model looks like.
     # import p-y curve for api_sand from openpile.utils
     from openpile.utils.py_curves import api_sand
 
-    p, y = api_sand(sig=50, # vertical stress in kPa 
+    y, p = api_sand(sig=50, # vertical stress in kPa 
                     X = 5, # depth in meter
                     phi = 35, # internal angle of friction 
                     D = 5, # the pile diameter
@@ -282,8 +285,8 @@ Example 5 - Create a Model and run an analysis
     M.set_pointload(elevation=0, Px=-20e3, Py=5e3)
 
     # Run analysis
-    from openpile.analyses import simple_winkler_analysis
-    Result = simple_winkler_analysis(M)
+    from openpile.analyze import winkler
+    Result = winkler(M)
 
     # plot the results
     Result.plot()