geolysis 0.4.2__py3-none-any.whl → 0.4.4__py3-none-any.whl

geolysis/__init__.py

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

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

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 . 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/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 . 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()

geolysis/bearing_capacity/abc/cohl/terzaghi_abc.py

@@ -0,0 +1,142 @@
+"""Terzaghi allowable bearing capacity.
+
+Classes
+=======
+
+.. autosummary::
+    :toctree: _autosummary
+
+    TerzaghiABC4PadFoundation
+    TerzaghiABC4MatFoundation
+"""
+from geolysis.foundation import FoundationSize
+from geolysis.utils import round_
+
+from . import AllowableBearingCapacity
+
+
+class TerzaghiABC4PadFoundation(AllowableBearingCapacity):
+    r"""Allowable bearing capacity for pad foundation on cohesionless
+    soils according to ``Terzaghi & Peck (1948)``.
+
+    :Equation:
+
+    .. math::
+
+         q_a(kPa) &= 12N \dfrac{1}{c_w 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\dfrac{1}
+                     {c_w f_d}\left(\dfrac{S}{25.4}\right), \ B \ \gt 1.2m
+
+         f_d &= 1 + 0.25 \cdot \frac{D_f}{B} \le 1.25
+
+         c_w &= 2 - \frac{D_w}{2B} \le 2, D_w \gt D_f
+
+         c_w &= 2 - \frac{D_f}{2B} \le 2, D_w \le D_f
+
+    ===================  ======================================  ===========
+     Symbol                Description                              Unit
+    ===================  ======================================  ===========
+    :math:`q_a`          Allowable bearing capacity               :math:`kPa`
+    :math:`N`            Corrected SPT N-value                     —
+    :math:`f_d`          Depth factor                              —
+    :math:`c_w`          Water correction factor                   —
+    :math:`S`            Tolerable settlement                     :math:`mm`
+    :math:`B`            Width of foundation footing              :math:`m`
+    :math:`D_f`          Depth of foundation footing              :math:`m`
+    :math:`D_w`          Depth of water below ground level        :math:`m`
+    ===================  ======================================  ===========
+    """
+
+    def __init__(self, corrected_spt_n_value: float,
+                 tol_settlement: float,
+                 foundation_size: FoundationSize) -> None:
+        """
+        :param corrected_spt_n_value: Lowest (or average) uncorrected SPT 
+                                      N-value (60% energy) 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)
+
+    def _fd(self) -> float:
+        """Calculate the depth factor."""
+        depth = self.foundation_size.depth
+        width = self.foundation_size.width
+
+        return min(1.0 + 0.25 * depth / width, 1.25)
+
+    def _cw(self):
+        """Calculate the water correction factor."""
+        depth = self.foundation_size.depth
+        width = self.foundation_size.width
+        water_level = self.foundation_size.ground_water_level
+
+        if water_level is None:
+            return 2.0
+
+        if water_level <= depth:
+            cw = 2.0 - depth / (2.0 * width)
+        else:
+            cw = 2.0 - water_level / (2.0 * width)
+
+        return min(cw, 2.0)
+
+    @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 * (1 / (self._cw() * self._fd())) * self._sr()
+
+        return (8 * n_corr * ((3.28 * width + 1) / (3.28 * width)) ** 2
+                * (1 / (self._cw() * self._fd())) * self._sr())
+
+
+class TerzaghiABC4MatFoundation(TerzaghiABC4PadFoundation):
+    r"""Allowable bearing capacity for mat foundation on cohesionless soils
+    according to ``Terzaghi & Peck (1948)``.
+
+    :Equation:
+
+    .. math::
+
+         q_a(kPa) &= 8N\dfrac{1}{c_w f_d}\left(\dfrac{S}{25.4}\right)
+
+         f_d &= 1 + 0.25 \cdot \frac{D_f}{B} \le 1.25
+
+         c_w &= 2 - \frac{D_w}{2B} \le 2, D_w \gt D_f
+
+         c_w &= 2 - \frac{D_f}{2B} \le 2, D_w \le D_f
+
+    ===================  ======================================  ===========
+     Symbol                Description                              Unit
+    ===================  ======================================  ===========
+    :math:`q_a`          Allowable bearing capacity               :math:`kPa`
+    :math:`N`            Corrected SPT N-value                     —
+    :math:`f_d`          Depth factor                              —
+    :math:`c_w`          Water correction factor                   —
+    :math:`S`            Tolerable settlement                     :math:`mm`
+    :math:`B`            Width of foundation footing              :math:`m`
+    :math:`D_f`          Depth of foundation footing              :math:`m`
+    :math:`D_w`          Depth of water below ground level        :math:`m`
+    ===================  ======================================  ===========
+    """
+
+    @round_
+    def bearing_capacity(self):
+        """Calculates the allowable bearing capacity of the mat foundation."""
+        n_corr = self.corrected_spt_n_value
+        return 8 * n_corr * (1 / (self._cw() * self._fd())) * self._sr()