geolysis 0.4.2__tar.gz → 0.4.4__tar.gz

{geolysis-0.4.2 → geolysis-0.4.4}/PKG-INFO

@@ -1,15 +1,15 @@
 Metadata-Version: 2.2
 Name: geolysis
-Version: 0.4.2
-Summary: geolysis.core is an opensource software for geotechnical engineering analysis and modeling.
+Version: 0.4.4
+Summary: geolysis is an opensource software for geotechnical engineering analysis and modeling.
 Author-email: Patrick Boateng <boatengpato.pb@gmail.com>
 License: MIT License
-Project-URL: Homepage, https://github.com/patrickboateng/geolysis
-Project-URL: Documentation, https://geolysis.readthedocs.org
+Project-URL: Homepage, https://docs.geolysis.io
+Project-URL: Documentation, https://docs.geolysis.io
 Project-URL: Repository, https://github.com/patrickboateng/geolysis
 Project-URL: Discussions, https://github.com/patrickboateng/geolysis/discussions
 Project-URL: Issue Tracker, https://github.com/patrickboateng/geolysis/issues
-Keywords: geotechnical-engineering,soil-classification,settlement-analysis,bearing-capacity-analysis
+Keywords: geotechnical-engineering,soil-classification,bearing-capacity-analysis,standard-penetration-test-analysis
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Education
@@ -29,14 +29,15 @@ Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: coverage; extra == "dev"
 
-<h1 align="center">
+<div align="center">
 <img src="https://raw.githubusercontent.com/patrickboateng/geolysis/dev/docs/source/_static/branding/geolysislogo.svg" 
 alt="geolysislogo" width="75%" />
-</h1><br>
+</div><br>
 
 <div align="center">
 
 [![PyPI Latest Release](https://img.shields.io/pypi/v/geolysis?style=flat&logo=pypi)](https://pypi.org/project/geolysis/)
+[![PyPI Downloads](https://static.pepy.tech/badge/geolysis)](https://pepy.tech/projects/geolysis)
 [![PyPI pyversions](https://img.shields.io/pypi/pyversions/geolysis.svg?logo=python&style=flat)](https://pypi.python.org/pypi/geolysis/)
 [![license](https://img.shields.io/pypi/l/geolysis?style=flat&logo=opensourceinitiative)](https://opensource.org/license/mit/)
 
@@ -116,106 +117,97 @@ Here are brief descriptions of these projects:
 
 ## Installation
 
-**_Note: Work on the latest update is still in progress, so the usage example
-below
-will not function if installed._**
-
 ```shell
-   pip install geolysis
+$ pip install geolysis
 ```
 
 ## Usage Example
 
 ```python
 
->> > from geolysis.soil_classifier import create_soil_classifier
->> > uscs_clf = create_soil_classifier(liquid_limit=34.1,
-                                       ...
-plastic_limit = 21.1,
-...
-fines = 47.88,
-...
-sand = 37.84,
-...
-clf_type = "USCS")
->> > clf = uscs_clf.classify()
->> > clf
+>>> from geolysis.soil_classifier import create_soil_classifier
+>>> uscs_clf = create_soil_classifier(liquid_limit=34.1,
+...                                   plastic_limit=21.1,
+...                                   fines=47.88,
+...                                   sand=37.84,
+...                                   clf_type="USCS")
+>>> clf = uscs_clf.classify()
+>>> clf
 SoilClf(symbol='SC', description='Clayey sands')
->> > clf.symbol
+>>> clf.symbol
 'SC'
->> > clf.description
+>>> clf.description
 'Clayey sands'
 
 ```
 
 ```python
 
->> > from geolysis.soil_classifier import create_soil_classifier
->> > aashto_clf = create_soil_classifier(liquid_limit=34.1,
-                                         ...
-plastic_limit = 21.1,
-...
-fines = 47.88,
-...
-sand = 37.84,  # Sand is optional for AASHTO classification
-...
-clf_type = "AASHTO")
->> > clf = aashto_clf.classify()
->> > clf
+>>> from geolysis.soil_classifier import create_soil_classifier
+>>> aashto_clf = create_soil_classifier(liquid_limit=34.1,
+...                                     plastic_limit=21.1,
+...                                     fines=47.88,
+...                                     sand=37.84,  # Sand is optional for AASHTO classification
+...                                     clf_type="AASHTO")
+>>> clf = aashto_clf.classify()
+>>> clf
 SoilClf(symbol='A-6(4)', description='Clayey soils')
->> > clf.symbol
+>>> clf.symbol
 'A-6(4)'
->> > clf.description
+>>> clf.description
 'Clayey soils'
 
 ```
 
+Check out more examples
+[here](https://docs.geolysis.io/en/latest/user_guide/getting_started.html#quick-start)
+
 ## Features
 
 <table>
-  <tr>
-    <td rowspan="2">
-    <strong>Soil Classification</strong>
-    </td>
-    <td>AASHTO Classification System</td>
-  </tr>
-  <tr>
-    <td>Unified Soil Classification System</td>
-  </tr>
-  <tr>
-    <td rowspan="4">
-    <strong>Standard Penetration Test (SPT) Analysis</strong>
-    </td>
-    <td>SPT Energy Correction</td>
-  </tr>
-  <tr>
-    <td>SPT Overburden Pressure Correction</td>
-  </tr>
-  <tr>
-    <td>Dilatancy Correction</td>
-  </tr>
-  <tr>
-    <td>SPT N-Design Calculation</td>
-  </tr>
-  <tr>
-    <td rowspan="2">
-    <strong>Bearing Capacity Estimation</strong>
-    </td>
-    <td>Allowable Bearing Capacity Estimation</td>
-  </tr>
-  <tr>
-    <td>Ultimate Bearing Capacity Estimation</td>
-  </tr>
+    <tr>
+        <td><strong>Soil Classification</strong></td>
+        <td>AASHTO Classification System</td>
+    </tr>
+    <tr>
+        <td></td>
+        <td>Unified Soil Classification System</td>
+    </tr>
+    <tr>
+        <td><strong>Standard Penetration Test (SPT) Analysis</strong></td>
+        <td>SPT Energy Correction</td>
+    </tr>
+    <tr>
+        <td></td>
+        <td>SPT Overburden Pressure Correction</td>
+    </tr>
+    <tr>
+        <td></td>
+        <td>Dilatancy Correction</td>
+    </tr>
+    <tr>
+        <td></td>
+        <td>SPT N-Design Calculation</td>
+    </tr>
+    <tr>
+        <td><strong>Bearing Capacity Estimation</strong></td>
+        <td>Allowable Bearing Capacity Estimation</td>
+    </tr>
+    <tr>
+        <td></td>
+        <td>Ultimate Bearing Capacity Estimation</td>
+    </tr>
 </table>
 
 ## Documentation
 
-Full documentation is available [here](https://www.geolysis.readthedocs.io)
-
-**_Note: Work on the latest documentation is still ongoing._**
+Full documentation is available [here](https://docs.geolysis.io/en/latest/)
 
 ## Contributing
 
+Contribution guidelines can be
+found [here](https://docs.geolysis.io/en/latest/dev_guide/index.html)
+
 ## License
 
 This project is licensed under the MIT License - see the

{geolysis-0.4.2 → geolysis-0.4.4}/README.md

@@ -1,11 +1,12 @@
-<h1 align="center">
+<div align="center">
 <img src="https://raw.githubusercontent.com/patrickboateng/geolysis/dev/docs/source/_static/branding/geolysislogo.svg" 
 alt="geolysislogo" width="75%" />
-</h1><br>
+</div><br>
 
 <div align="center">
 
 [![PyPI Latest Release](https://img.shields.io/pypi/v/geolysis?style=flat&logo=pypi)](https://pypi.org/project/geolysis/)
+[![PyPI Downloads](https://static.pepy.tech/badge/geolysis)](https://pepy.tech/projects/geolysis)
 [![PyPI pyversions](https://img.shields.io/pypi/pyversions/geolysis.svg?logo=python&style=flat)](https://pypi.python.org/pypi/geolysis/)
 [![license](https://img.shields.io/pypi/l/geolysis?style=flat&logo=opensourceinitiative)](https://opensource.org/license/mit/)
 
@@ -85,106 +86,97 @@ Here are brief descriptions of these projects:
 
 ## Installation
 
-**_Note: Work on the latest update is still in progress, so the usage example
-below
-will not function if installed._**
-
 ```shell
-   pip install geolysis
+$ pip install geolysis
 ```
 
 ## Usage Example
 
 ```python
 
->> > from geolysis.soil_classifier import create_soil_classifier
->> > uscs_clf = create_soil_classifier(liquid_limit=34.1,
-                                       ...
-plastic_limit = 21.1,
-...
-fines = 47.88,
-...
-sand = 37.84,
-...
-clf_type = "USCS")
->> > clf = uscs_clf.classify()
->> > clf
+>>> from geolysis.soil_classifier import create_soil_classifier
+>>> uscs_clf = create_soil_classifier(liquid_limit=34.1,
+...                                   plastic_limit=21.1,
+...                                   fines=47.88,
+...                                   sand=37.84,
+...                                   clf_type="USCS")
+>>> clf = uscs_clf.classify()
+>>> clf
 SoilClf(symbol='SC', description='Clayey sands')
->> > clf.symbol
+>>> clf.symbol
 'SC'
->> > clf.description
+>>> clf.description
 'Clayey sands'
 
 ```
 
 ```python
 
->> > from geolysis.soil_classifier import create_soil_classifier
->> > aashto_clf = create_soil_classifier(liquid_limit=34.1,
-                                         ...
-plastic_limit = 21.1,
-...
-fines = 47.88,
-...
-sand = 37.84,  # Sand is optional for AASHTO classification
-...
-clf_type = "AASHTO")
->> > clf = aashto_clf.classify()
->> > clf
+>>> from geolysis.soil_classifier import create_soil_classifier
+>>> aashto_clf = create_soil_classifier(liquid_limit=34.1,
+...                                     plastic_limit=21.1,
+...                                     fines=47.88,
+...                                     sand=37.84,  # Sand is optional for AASHTO classification
+...                                     clf_type="AASHTO")
+>>> clf = aashto_clf.classify()
+>>> clf
 SoilClf(symbol='A-6(4)', description='Clayey soils')
->> > clf.symbol
+>>> clf.symbol
 'A-6(4)'
->> > clf.description
+>>> clf.description
 'Clayey soils'
 
 ```
 
+Check out more examples
+[here](https://docs.geolysis.io/en/latest/user_guide/getting_started.html#quick-start)
+
 ## Features
 
 <table>
-  <tr>
-    <td rowspan="2">
-    <strong>Soil Classification</strong>
-    </td>
-    <td>AASHTO Classification System</td>
-  </tr>
-  <tr>
-    <td>Unified Soil Classification System</td>
-  </tr>
-  <tr>
-    <td rowspan="4">
-    <strong>Standard Penetration Test (SPT) Analysis</strong>
-    </td>
-    <td>SPT Energy Correction</td>
-  </tr>
-  <tr>
-    <td>SPT Overburden Pressure Correction</td>
-  </tr>
-  <tr>
-    <td>Dilatancy Correction</td>
-  </tr>
-  <tr>
-    <td>SPT N-Design Calculation</td>
-  </tr>
-  <tr>
-    <td rowspan="2">
-    <strong>Bearing Capacity Estimation</strong>
-    </td>
-    <td>Allowable Bearing Capacity Estimation</td>
-  </tr>
-  <tr>
-    <td>Ultimate Bearing Capacity Estimation</td>
-  </tr>
+    <tr>
+        <td><strong>Soil Classification</strong></td>
+        <td>AASHTO Classification System</td>
+    </tr>
+    <tr>
+        <td></td>
+        <td>Unified Soil Classification System</td>
+    </tr>
+    <tr>
+        <td><strong>Standard Penetration Test (SPT) Analysis</strong></td>
+        <td>SPT Energy Correction</td>
+    </tr>
+    <tr>
+        <td></td>
+        <td>SPT Overburden Pressure Correction</td>
+    </tr>
+    <tr>
+        <td></td>
+        <td>Dilatancy Correction</td>
+    </tr>
+    <tr>
+        <td></td>
+        <td>SPT N-Design Calculation</td>
+    </tr>
+    <tr>
+        <td><strong>Bearing Capacity Estimation</strong></td>
+        <td>Allowable Bearing Capacity Estimation</td>
+    </tr>
+    <tr>
+        <td></td>
+        <td>Ultimate Bearing Capacity Estimation</td>
+    </tr>
 </table>
 
 ## Documentation
 
-Full documentation is available [here](https://www.geolysis.readthedocs.io)
-
-**_Note: Work on the latest documentation is still ongoing._**
+Full documentation is available [here](https://docs.geolysis.io/en/latest/)
 
 ## Contributing
 
+Contribution guidelines can be
+found [here](https://docs.geolysis.io/en/latest/dev_guide/index.html)
+
 ## License
 
 This project is licensed under the MIT License - see the

geolysis-0.4.4/geolysis/__init__.py

@@ -0,0 +1,5 @@
+from . import foundation, soil_classifier, spt
+
+__version__ = "0.4.4"
+
+__all__ = ["foundation", "soil_classifier", "spt"]

geolysis-0.4.4/geolysis/bearing_capacity/abc/cohl/__init__.py

@@ -0,0 +1,206 @@
+""" Allowable bearing capacity package for cohesionless soils.
+
+Exceptions
+==========
+
+.. autosummary::
+    :toctree: _autosummary
+
+    SettlementError
+
+Enums
+=====
+
+.. autosummary::
+    :toctree: _autosummary
+    :nosignatures:
+
+    ABC_TYPE
+
+Functions
+=========
+
+.. autosummary::
+    :toctree: _autosummary
+
+    create_allowable_bearing_capacity
+"""
+import enum
+from abc import ABC, abstractmethod
+from typing import Optional
+
+from geolysis.foundation import (FoundationSize,
+                                 Shape,
+                                 FoundationType,
+                                 create_foundation)
+from geolysis.utils import inf, enum_repr, validators
+
+
+class SettlementError(ValueError):
+    """Raised when tolerable settlement is greater than the maximum 
+    allowable settlement.
+    """
+
+
+class AllowableBearingCapacity(ABC):
+    #: Maximum tolerable foundation settlement (mm).
+    MAX_TOL_SETTLEMENT = 25.4
+
+    def __init__(self, corrected_spt_n_value: float,
+                 tol_settlement: float,
+                 foundation_size: FoundationSize) -> None:
+        self.corrected_spt_n_value = corrected_spt_n_value
+        self.tol_settlement = tol_settlement
+        self.foundation_size = foundation_size
+
+    @property
+    def corrected_spt_n_value(self) -> float:
+        return self._corrected_spt_n_value
+
+    @corrected_spt_n_value.setter
+    @validators.ge(0.0)
+    def corrected_spt_n_value(self, val: float) -> None:
+        self._corrected_spt_n_value = val
+
+    @property
+    def tol_settlement(self) -> float:
+        return self._tol_settlement
+
+    @tol_settlement.setter
+    @validators.le(25.4, exc_type=SettlementError)
+    def tol_settlement(self, tol_settlement: float) -> None:
+        self._tol_settlement = tol_settlement
+
+    def _sr(self) -> float:
+        """Calculate the settlement ratio."""
+        return self.tol_settlement / self.MAX_TOL_SETTLEMENT
+
+    def _fd(self) -> float:
+        """Calculate the depth factor."""
+        depth = self.foundation_size.depth
+        width = self.foundation_size.width
+
+        return min(1.0 + 0.33 * depth / width, 1.33)
+
+    @abstractmethod
+    def bearing_capacity(self): ...
+
+
+from . import bowles_abc, terzaghi_abc, meyerhof_abc
+
+from .bowles_abc import BowlesABC4MatFoundation, BowlesABC4PadFoundation
+from .meyerhof_abc import MeyerhofABC4MatFoundation, MeyerhofABC4PadFoundation
+from .terzaghi_abc import TerzaghiABC4MatFoundation, TerzaghiABC4PadFoundation
+
+
+@enum_repr
+class ABC_TYPE(enum.StrEnum):
+    """Enumeration of available allowable bearing capacity types."""
+    BOWLES = enum.auto()
+    MEYERHOF = enum.auto()
+    TERZAGHI = enum.auto()
+
+
+def create_allowable_bearing_capacity(corrected_spt_n_value: float,
+                                      tol_settlement: float,
+                                      depth: float,
+                                      width: float,
+                                      length: Optional[float] = None,
+                                      eccentricity: float = 0.0,
+                                      ground_water_level: float = inf,
+                                      shape: Shape | str = Shape.SQUARE,
+                                      foundation_type: FoundationType | str = \
+                                              FoundationType.PAD,
+                                      abc_type: Optional[
+                                          ABC_TYPE | str] = None,
+                                      ) -> AllowableBearingCapacity:
+    """ A factory function that encapsulate the creation of  allowable bearing
+    capacities.
+
+    :param corrected_spt_n_value: The corrected SPT N-value.
+    :type corrected_spt_n_value: float
+
+    :param tol_settlement: Tolerable settlement of foundation (mm).
+    :type tol_settlement: float
+
+    :param depth: Depth of foundation (m).
+    :type depth: float
+
+    :param width: Width of foundation footing (m).
+    :type width: float
+
+    :param length: Length of foundation footing (m).
+    :type length: float, optional
+
+    :param eccentricity: The deviation of the foundation load from the center 
+                         of gravity of the foundation footing, defaults to 0.0.
+                         This means that the foundation load aligns with the
+                         center of gravity of the foundation footing (m).
+    :type eccentricity: float, optional
+
+    :param ground_water_level: Depth of water below ground level (m).
+    :type ground_water_level: float
+
+    :param shape: Shape of foundation footing, defaults to "SQUARE".
+    :type shape: str, optional
+
+    :param foundation_type: Type of foundation, defaults to "pad".
+    :type foundation_type: FoundationType | str, optional
+
+    :param abc_type: Type of allowable bearing capacity calculation to apply.
+                     Available values can be found in :class:`ABC_TYPE`,
+                     defaults to None.
+    :type abc_type:  ABC_TYPE | str
+
+    :raises ValueError: Raised if abc_type or foundation_type is not supported.
+    :raises ValueError: Raised when length is not provided for a rectangular
+                        footing.
+    :raises ValueError: Raised if an invalid footing shape is provided.
+    """
+    msg = (f"{abc_type = } is not supported, Supported "
+           f"types are: {list(ABC_TYPE)}")
+
+    if abc_type is None:
+        raise ValueError(msg)
+
+    try:
+        abc_type = ABC_TYPE(str(abc_type).casefold())
+    except ValueError as e:
+        raise ValueError(msg) from e
+
+    msg = (f"{foundation_type = } is not supported, Supported "
+           f"types are: {list(FoundationType)}")
+
+    try:
+        foundation_type = FoundationType(str(foundation_type).casefold())
+    except ValueError as e:
+        raise ValueError(msg) from e
+
+    # exception from create_foundation will automaatically propagate
+    # no need to catch and handle it.
+    fnd_size = create_foundation(depth=depth,
+                                 width=width,
+                                 length=length,
+                                 eccentricity=eccentricity,
+                                 ground_water_level=ground_water_level,
+                                 shape=shape)
+    abc_classes = {
+        ABC_TYPE.BOWLES: {
+            FoundationType.PAD: BowlesABC4PadFoundation,
+            FoundationType.MAT: BowlesABC4MatFoundation,
+        },
+        ABC_TYPE.MEYERHOF: {
+            FoundationType.PAD: MeyerhofABC4PadFoundation,
+            FoundationType.MAT: MeyerhofABC4MatFoundation,
+        },
+        ABC_TYPE.TERZAGHI: {
+            FoundationType.PAD: TerzaghiABC4PadFoundation,
+            FoundationType.MAT: TerzaghiABC4MatFoundation,
+        }
+    }
+
+    abc_class = abc_classes[abc_type][foundation_type]
+    abc = abc_class(corrected_spt_n_value=corrected_spt_n_value,
+                    tol_settlement=tol_settlement,
+                    foundation_size=fnd_size)
+    return abc