geolysis 0.4.3__tar.gz → 0.4.5__tar.gz

{geolysis-0.4.3 → geolysis-0.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: geolysis
-Version: 0.4.3
+Version: 0.4.5
 Summary: geolysis is an opensource software for geotechnical engineering analysis and modeling.
 Author-email: Patrick Boateng <boatengpato.pb@gmail.com>
 License: MIT License
@@ -28,6 +28,7 @@ Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: coverage; extra == "dev"
+Dynamic: license-file
 
 <div align="center">
 <img src="https://raw.githubusercontent.com/patrickboateng/geolysis/dev/docs/source/_static/branding/geolysislogo.svg" 
@@ -147,7 +148,6 @@ SoilClf(symbol='SC', description='Clayey sands')
 >>> 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
@@ -159,18 +159,45 @@ SoilClf(symbol='A-6(4)', description='Clayey soils')
 
 ```
 
+Check out more examples
+[here](https://docs.geolysis.io/en/latest/user_guide/getting_started.html#quick-start)
+
 ## Features
 
-|                                              |                                       |
-|----------------------------------------------|---------------------------------------|
-| **Soil Classification**                      | AASHTO Classification System          |
-|                                              | Unified Soil Classification System    |
-| **Standard Penetration Test (SPT) Analysis** | SPT Energy Correction                 |
-|                                              | SPT Overburden Pressure Correction    |
-|                                              | Dilatancy Correction                  |
-|                                              | SPT N-Design Calculation              |
-| **Bearing Capacity Estimation**              | Allowable Bearing Capacity Estimation |
-|                                              | Ultimate Bearing Capacity Estimation  |
+<table>
+    <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
 

{geolysis-0.4.3 → geolysis-0.4.5}/README.md

@@ -116,7 +116,6 @@ SoilClf(symbol='SC', description='Clayey sands')
 >>> 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
@@ -128,18 +127,45 @@ SoilClf(symbol='A-6(4)', description='Clayey soils')
 
 ```
 
+Check out more examples
+[here](https://docs.geolysis.io/en/latest/user_guide/getting_started.html#quick-start)
+
 ## Features
 
-|                                              |                                       |
-|----------------------------------------------|---------------------------------------|
-| **Soil Classification**                      | AASHTO Classification System          |
-|                                              | Unified Soil Classification System    |
-| **Standard Penetration Test (SPT) Analysis** | SPT Energy Correction                 |
-|                                              | SPT Overburden Pressure Correction    |
-|                                              | Dilatancy Correction                  |
-|                                              | SPT N-Design Calculation              |
-| **Bearing Capacity Estimation**              | Allowable Bearing Capacity Estimation |
-|                                              | Ultimate Bearing Capacity Estimation  |
+<table>
+    <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
 

geolysis-0.4.5/geolysis/__init__.py

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

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

@@ -0,0 +1,146 @@
+""" Allowable bearing capacity package for cohesionless soils.
+
+Enums
+=====
+
+.. autosummary::
+    :toctree: _autosummary
+    :nosignatures:
+
+    ABCType
+
+Functions
+=========
+
+.. autosummary::
+    :toctree: _autosummary
+
+    create_allowable_bearing_capacity
+"""
+
+import enum
+from typing import Optional
+
+from geolysis.foundation import FoundationType, Shape, create_foundation
+from geolysis.utils import enum_repr, inf
+
+from ._core import AllowableBearingCapacity
+from .bowles_abc import BowlesABC4MatFoundation, BowlesABC4PadFoundation
+from .meyerhof_abc import MeyerhofABC4MatFoundation, MeyerhofABC4PadFoundation
+from .terzaghi_abc import TerzaghiABC4MatFoundation, TerzaghiABC4PadFoundation
+
+
+@enum_repr
+class ABCType(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[
+                                          ABCType | 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 (m), defaults to
+                         0.0. This means that the foundation load aligns with
+                         the center of gravity of the foundation footing.
+    :type eccentricity: float, optional
+
+    :param ground_water_level: Depth of water below ground level (m).
+    :type ground_water_level: float, optional
+
+    :param shape: Shape of foundation footing, defaults to
+                  :attr:`~geolysis.foundation.Shape.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:`ABCType`,
+                     defaults to None.
+    :type abc_type:  ABCType | str, optional
+
+    :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(ABCType)}")
+
+    if abc_type is None:
+        raise ValueError(msg)
+
+    try:
+        abc_type = ABCType(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,
+                                 foundation_type=foundation_type,
+                                 shape=shape)
+    abc_classes = {
+        ABCType.BOWLES: {
+            FoundationType.PAD: BowlesABC4PadFoundation,
+            FoundationType.MAT: BowlesABC4MatFoundation,
+        },
+        ABCType.MEYERHOF: {
+            FoundationType.PAD: MeyerhofABC4PadFoundation,
+            FoundationType.MAT: MeyerhofABC4MatFoundation,
+        },
+        ABCType.TERZAGHI: {
+            FoundationType.PAD: TerzaghiABC4PadFoundation,
+            FoundationType.MAT: TerzaghiABC4MatFoundation,
+        }
+    }
+
+    abc_class = abc_classes[abc_type][fnd_size.foundation_type]
+    abc = abc_class(corrected_spt_n_value=corrected_spt_n_value,
+                    tol_settlement=tol_settlement,
+                    foundation_size=fnd_size)
+    return abc

geolysis-0.4.5/geolysis/bearing_capacity/abc/cohl/_core.py

@@ -0,0 +1,55 @@
+from abc import ABC, abstractmethod
+
+from geolysis.foundation import FoundationSize
+from geolysis.utils import 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:
+        """Statistical average of corrected SPT N-value."""
+        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:
+        """Tolerable settlement foundation (mm)."""
+        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): ...

geolysis-0.4.5/geolysis/bearing_capacity/abc/cohl/bowles_abc.py

@@ -0,0 +1,107 @@
+""" Bowles allowable bearing capacity.
+
+Classes
+=======
+
+.. autosummary::
+    :toctree: _autosummary
+
+    BowlesABC4PadFoundation
+    BowlesABC4MatFoundation
+"""
+from geolysis.foundation import FoundationSize
+from geolysis.utils import round_
+
+from ._core import AllowableBearingCapacity
+
+
+class BowlesABC4PadFoundation(AllowableBearingCapacity):
+    r"""Allowable bearing capacity for pad foundation on cohesionless soils
+    according to ``Bowles (1997)``.
+
+    :Equation:
+
+    .. math::
+
+        q_a(kPa) &= 19.16(N_1)_{55} f_d\left(\dfrac{S}{25.4}\right),
+                        \ B \ \le \ 1.2m
+
+        q_a(kPa) &= 11.98(N_1)_{55}\left(\dfrac{3.28B + 1}{3.28B} \right)^2
+                        f_d \left(\dfrac{S}{25.4}\right), \ B \ \gt 1.2m
+
+        f_d &= 1 + 0.33 \cdot \frac{D_f}{B} \le 1.33
+
+    ===================  ======================================  ===========
+     Symbol                Description                              Unit
+    ===================  ======================================  ===========
+    :math:`q_a`          Allowable bearing capacity               :math:`kPa`
+    :math:`(N_1)_{55}`   Corrected SPT N-value                     —
+    :math:`f_d`          Depth factor                              —
+    :math:`S`            Tolerable settlement                     :math:`mm`
+    :math:`B`            Width of foundation footing              :math:`m`
+    :math:`D_f`          Depth of foundation footing              :math:`m`
+    ===================  ======================================  ===========
+    """
+
+    def __init__(self, corrected_spt_n_value: float,
+                 tol_settlement: float,
+                 foundation_size: FoundationSize) -> None:
+        """
+        :param corrected_spt_n_value: Statistical average of corrected SPT
+                                      N-value (55% energy with overburden 
+                                      pressure correction) within the foundation 
+                                      influence zone i.e ``0.5B`` to ``2B``.
+        :type corrected_spt_n_value: float
+
+        :param tol_settlement: Tolerable settlement of foundation (mm).
+        :type tol_settlement: float
+
+        :param foundation_size: Size of the foundation.
+        :type foundation_size: FoundationSize
+        """
+        super().__init__(corrected_spt_n_value=corrected_spt_n_value,
+                         tol_settlement=tol_settlement,
+                         foundation_size=foundation_size)
+
+    @round_
+    def bearing_capacity(self) -> float:
+        """Calculate the allowable bearing capacity of the pad foundation."""
+        n_corr = self.corrected_spt_n_value
+        width = self.foundation_size.width
+
+        if width <= 1.2:
+            return 19.16 * n_corr * self._fd() * self._sr()
+
+        return (11.98 * n_corr * ((3.28 * width + 1) / (3.28 * width)) ** 2
+                * self._fd() * self._sr())
+
+
+class BowlesABC4MatFoundation(BowlesABC4PadFoundation):
+    r"""Allowable bearing capacity for mat foundation on cohesionless soils
+    according to ``Bowles (1997)``.
+
+    :Equation:
+
+    .. math::
+
+         q_a(kPa) &= 11.98(N_1)_{55}f_d\left(\dfrac{S}{25.4}\right)
+
+         f_d &= 1 + 0.33 \cdot \frac{D_f}{B} \le 1.33
+
+    ===================  ======================================  ===========
+     Symbol                Description                              Unit
+    ===================  ======================================  ===========
+    :math:`q_a`          Allowable bearing capacity               :math:`kPa`
+    :math:`(N_1)_{55}`   Corrected SPT N-value                     —
+    :math:`f_d`          Depth factor                              —
+    :math:`S`            Tolerable settlement                     :math:`mm`
+    :math:`B`            Width of foundation footing              :math:`m`
+    :math:`D_f`          Depth of foundation footing              :math:`m`
+    ===================  ======================================  ===========
+    """
+
+    @round_
+    def bearing_capacity(self) -> float:
+        """Calculate the allowable bearing capacity of the mat foundation."""
+        n_corr = self.corrected_spt_n_value
+        return 11.98 * n_corr * self._fd() * self._sr()

geolysis-0.4.5/geolysis/bearing_capacity/abc/cohl/meyerhof_abc.py

@@ -0,0 +1,107 @@
+""" Meyerhof allowable bearing capacity.
+
+Classes
+=======
+
+.. autosummary::
+    :toctree: _autosummary
+
+    MeyerhofABC4PadFoundation
+    MeyerhofABC4MatFoundation
+"""
+from geolysis.foundation import FoundationSize
+from geolysis.utils import round_
+
+from ._core import AllowableBearingCapacity
+
+
+class MeyerhofABC4PadFoundation(AllowableBearingCapacity):
+    r"""Allowable bearing capacity for pad foundation on cohesionless soils
+    according to ``Meyerhof (1956)``.
+
+    :Equation:
+
+    .. math::
+
+         q_a(kPa) &= 12N f_d\left(\dfrac{S}{25.4}\right), \ B \ \le 1.2m
+
+         q_a(kPa) &= 8N\left(\dfrac{3.28B + 1}{3.28B} \right)^2 f_d\left(
+                 \dfrac{S}{25.4}\right), \ B \ \gt 1.2m
+
+         f_d &= 1 + 0.33 \cdot \frac{D_f}{B} \le 1.33
+
+    ===================  ======================================  ===========
+     Symbol                Description                              Unit
+    ===================  ======================================  ===========
+    :math:`q_a`          Allowable bearing capacity               :math:`kPa`
+    :math:`N`            Corrected SPT N-value                     —
+    :math:`f_d`          Depth factor                              —
+    :math:`S`            Tolerable settlement                     :math:`mm`
+    :math:`B`            Width of foundation footing              :math:`m`
+    :math:`D_f`          Depth of foundation footing              :math:`m`
+    ===================  ======================================  ===========
+    """
+
+    def __init__(self, corrected_spt_n_value: float,
+                 tol_settlement: float,
+                 foundation_size: FoundationSize):
+        """
+        :param corrected_spt_n_value: Average uncorrected SPT N-value (60% 
+                                      energy with dilatancy (water) correction 
+                                      if applicable) within the foundation 
+                                      influence  zone i.e :math:`D_f` to
+                                      :math:`D_f + 2B`.
+        :type corrected_spt_n_value: float
+
+        :param tol_settlement: Tolerable settlement of foundation (mm).
+        :type tol_settlement: float
+
+        :param foundation_size: Size of the foundation.
+        :type foundation_size: FoundationSize
+        """
+        super().__init__(corrected_spt_n_value=corrected_spt_n_value,
+                         tol_settlement=tol_settlement,
+                         foundation_size=foundation_size)
+
+    @round_
+    def bearing_capacity(self):
+        """Calculates the allowable bearing capacity of the pad foundation."""
+        n_corr = self.corrected_spt_n_value
+        width = self.foundation_size.width
+
+        if width <= 1.2:
+            return 12 * n_corr * self._fd() * self._sr()
+
+        return (8 * n_corr * ((3.28 * width + 1) / (3.28 * width)) ** 2
+                * self._fd() * self._sr())
+
+
+class MeyerhofABC4MatFoundation(MeyerhofABC4PadFoundation):
+    r"""Allowable bearing capacity for mat foundation on cohesionless soils
+    according to ``Meyerhof (1956)``.
+
+    :Equation:
+
+    .. math::
+
+         q_a(kPa) &= 8 N f_d\left(\dfrac{S}{25.4}\right)
+
+         f_d &= 1 + 0.33 \cdot \frac{D_f}{B} \le 1.33
+
+    ===================  ======================================  ===========
+     Symbol                Description                              Unit
+    ===================  ======================================  ===========
+    :math:`q_a`          Allowable bearing capacity               :math:`kPa`
+    :math:`N`            Corrected SPT N-value                     —
+    :math:`f_d`          Depth factor                              —
+    :math:`S`            Tolerable settlement                     :math:`mm`
+    :math:`B`            Width of foundation footing              :math:`m`
+    :math:`D_f`          Depth of foundation footing              :math:`m`
+    ===================  ======================================  ===========
+    """
+
+    @round_
+    def bearing_capacity(self):
+        """Calculate the allowable bearing capacity of the mat foundation."""
+        n_corr = self.corrected_spt_n_value
+        return 8 * n_corr * self._fd() * self._sr()