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

Extras doc unit testing and more

.gitignore

@@ -6,6 +6,9 @@ __pycache__/
 # C extensions
 *.so
 
+# MacOs
+.DS_Store
+
 # Distribution / packaging
 .Python
 build/

.vscode/settings.json

@@ -3,5 +3,6 @@
         "test"
     ],
     "python.testing.unittestEnabled": false,
-    "python.testing.pytestEnabled": true
+    "python.testing.pytestEnabled": true,
+    "python.formatting.provider": "black"
 }

CHANGELOG.md

@@ -0,0 +1,24 @@
+Changelog
+---------
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/)
+and this project adheres to [Semantic Versioning](http://semver.org/),
+and [PEP 440](https://www.python.org/dev/peps/pep-0440/).
+
+## [0.1.0] - 2023-04-10
+### Added
+- PISA sand and clay models (called Dunkirk_sand and Cowden_clay models)
+- Rotational springs and base springs (shear and moment), see `utils` module
+- New set of unit tests covering the `Construct` module, coverage is not 100%.
+
+## [0.0.1] - 2023-03-31
+### Notes
+- first release of openpile with simple beam and simple winkler analysis with lateral springs
+
+### Added
+- `Construct` module with Pile, SoilProfile, Layer, and Model objects
+- `utils` module with py curves
+- `Analysis`modile with `simple_beam_analysis()` and `simple_winkler_analysis()`
+- `Result` class that provides the user with plotting and Pandas Dataframe overview of results. 

README.md

@@ -1,4 +1,4 @@
-# openpile
+# OpenPile
 
 Geotechnical super-toolbox for pile-related calculations.
 
@@ -48,7 +48,7 @@ pip install openpile
 
  ## Please share with the community
 
-This library relies on community interactions. Please consider sharing a post about `openpile` and the value it can provide for researcher, academia and professionals.
+This library relies on community interactions. Please consider sharing a post about `OpenPile` and the value it can provide for researcher, academia and professionals.
 
 [![GitHub Repo stars](https://img.shields.io/badge/share%20on-reddit-red?logo=reddit)](https://reddit.com/submit?url=https://github.com/TchilDill/openpile&title=openpile)
 [![GitHub Repo stars](https://img.shields.io/badge/share%20on-twitter-03A9F4?logo=twitter)](https://twitter.com/share?url=https://github.com/TchilDill/openpile&t=openpile)

docs/source/API.rst

@@ -4,12 +4,42 @@ API
 
 .. automodule:: openpile.construct
     :members:
-    :exclude-members: __init__, PydanticConfig
+    :exclude-members: __init__, PydanticConfig, soil_and_pile_bottom_elevation_match
+
+
+.. automodule:: openpile.soilmodels
+    :members: 
+    :exclude-members: __init__, PydanticConfig, PydanticConfigFrozen, ConstitutiveModel, LateralModel, AxialModel
+
 
 .. automodule:: openpile.analyses
     :members: 
     :exclude-members: PydanticConfig, structural_forces_to_df, disp_to_df, Result
 
+
+`utils` module
+==============
+
+.. automodule:: openpile.utils.py_curves
+    :members:
+    :exclude-members: random
+
+
+.. automodule:: openpile.utils.mt_curves
+    :members:
+    :exclude-members: random
+
+
+.. automodule:: openpile.utils.tz_curves
+    :members:
+    :exclude-members: random
+
+
+.. automodule:: openpile.utils.qz_curves
+    :members:
+    :exclude-members: random
+
+
 The `Result` class
 ==================
 

docs/source/about.rst

@@ -2,39 +2,87 @@
 About
 -----
 
-This package is an open source python package that provides a tool box for geotechnical pile
-calculations.  
+This package is an open source python library that provides users a tool box for geotechnical pile
+calculations.
+
+This package allows the user to:
+
+* Use basic Euler-Bernoulli beam theory (as well as Timoshenko's variation) to compute 
+  forces, deflection of a beam (or a pile) under adequate loading conditions and 
+  support conditions.
+* Use Winkler's approach of a beam (or a pile) supported by non-linear lateral and/or 
+  rotational springs to compute forces and deflection of the pile based on recognised 
+  soil models such as the widely known API models for sand and clay or more recent models that stem from 
+  the PISA joint-industry project.
+
+You must have a version of python installed on your machine (supported versions: 3.7-3.10)
+
 
 Installation
-------------
+^^^^^^^^^^^^
 
 .. code-block:: console
 
     pip install openpile
 
 
-You must have the following to execute the above command:
+Via the generic Python distribution
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+#. Go to the official Python website at https://www.python.org/downloads/ and 
+   download python for your operating system (Windows, macOS, or Linux).
+   **Note that only python version ranging from 3.7 to 3.10 are valid for openpile to run.**
+#. Run the installer and follow the prompts to complete the installation process.
+#. After installing Python, open a terminal or command prompt and type python to verify that 
+   Python is installed correctly. You should see the Python version number.
+#. To start using Python packages, you can use the built-in package manager called pip. 
+   Type pip or pip3 (depending on your installation) in the terminal to see if it's installed correctly.
+#. To install the awesome OpenPile package, use the command:
+
+   .. code-block::
+    
+      pip install openpile
+      
+   This will download and install the package and all its dependencies.
+
+
+Via the Anaconda distribution
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-* a version of python installed on your machine (supported versions: 3.7-3.10)
-* pip is installed in your environment.
+#. Download and install the latest version of Anaconda from https://www.anaconda.com/products/individual.
+#. Open the Anaconda Navigator application and select the "Environments" tab.
+#. Click the "Create" button to create a new environment and enter a name for it (e.g. python37).
+#. Select the desired Python version from the dropdown menu (e.g. Python 3.7) and click the "Create" button.
+#. Repeat the previous steps to create environments for the other Python versions you want to install (e.g. 
+   python38, python39, python310).
+#. To switch to a specific environment, select it from the list and click the "Activate" button.
+#. To install a package in the environment using pip, open a terminal window by clicking the 
+   "Open Terminal" button in the "Environments" tab.
+#. Use the following command to install a package using pip in the environment:
+
+   .. code-block:: console
 
+      pip install openpile
 
-Features 
---------
 
-* Python 3.7-3.10 support
-* Interactive structure perfectly suited for Jupyter Notebook 
-* Integrated data validation to prevent wrong inputs with pydantic
-* Calculations
 
-  * Beam calculation
-  * Winkler model (i.e. beam supported by soil springs)
+Disclaimer
+^^^^^^^^^^
 
-    * Load-driven analyses
-    * Displacement-driven analyses 
+This open source package is primarily provided for educational and research purposes. 
+It is not intended to replace professional engineering advice or analyses. 
+The analyses performed using this package may not accurately 
+represent real-world situations or account for all possible variables and conditions.
 
-  * Out-of-the-box computation of individual soil springs
+Users of this package assume all responsibility and liability for any consequences
+resulting from its use. The developers and contributors of this package make no 
+warranties or guarantees, express or implied, regarding its accuracy, reliability,
+or fitness for any particular purpose.
 
-* Friendly API interface with  object-oriented approach
-* Fully integrated output with python environment with Matplotlib and Pandas libraries. 
+Users should exercise caution and use their professional judgement when interpreting
+and applying the results generated by this package. In addition, users should be aware
+that the laws and regulations governing the use of finite element analyses may vary
+depending on their location and industry, and should comply with all 
+applicable laws and regulations.
 
+By using this package, users acknowledge and agree to the terms of this disclaimer.

docs/source/conf.py

@@ -6,7 +6,7 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = 'openpile'
+project = 'OpenPile'
 copyright = '2023, Guillaume Melin'
 author = 'Guillaume Melin'
 

pyproject.toml

@@ -8,3 +8,5 @@ testpaths = [
     "test",
 ] 
 
+[tool.black]
+line-length = 100

src/openpile/analyses.py

@@ -305,9 +305,14 @@ def simple_winkler_analysis(model, solver="NR", max_iter: int = 100):
             if solver == "NR":
                 K = kernel.build_stiffness_matrix(model, u=d, kind="tangent")
             elif solver == "MNR":
-                pass
-
-            # reset displacements in case of displacement-driven analysis
+                if model.distributed_moment:
+                    pass
+                    # K = kernel.build_stiffness_matrix(model, u=d, kind="initial")
+                else:
+                    pass
+
+            # reset prescribed displacements to converge properly in case
+            # of displacement-driven analysis
             U[:] = 0.0
 
         # Internal forces calculations with dim(nelem,6,6)