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

geolysis/__init__.py

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

geolysis/bearing_capacity/abc/cohl/__init__.py

@@ -1,13 +1,5 @@
 """ Allowable bearing capacity package for cohesionless soils.
 
-Exceptions
-==========
-
-.. autosummary::
-    :toctree: _autosummary
-
-    SettlementError
-
 Enums
 =====
 
@@ -15,7 +7,7 @@ Enums
     :toctree: _autosummary
     :nosignatures:
 
-    ABC_TYPE
+    ABCType
 
 Functions
 =========
@@ -25,76 +17,21 @@ Functions
 
     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 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 ABC_TYPE(enum.StrEnum):
+class ABCType(enum.StrEnum):
     """Enumeration of available allowable bearing capacity types."""
     BOWLES = enum.auto()
     MEYERHOF = enum.auto()
@@ -109,10 +46,10 @@ def create_allowable_bearing_capacity(corrected_spt_n_value: float,
                                       eccentricity: float = 0.0,
                                       ground_water_level: float = inf,
                                       shape: Shape | str = Shape.SQUARE,
-                                      foundation_type: FoundationType | str = \
-                                              FoundationType.PAD,
+                                      foundation_type: FoundationType | str =
+                                      FoundationType.PAD,
                                       abc_type: Optional[
-                                          ABC_TYPE | str] = None,
+                                          ABCType | str] = None,
                                       ) -> AllowableBearingCapacity:
     """ A factory function that encapsulate the creation of  allowable bearing
     capacities.
@@ -133,42 +70,44 @@ def create_allowable_bearing_capacity(corrected_spt_n_value: float,
     :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).
+                         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
+    :type ground_water_level: float, optional
 
-    :param shape: Shape of foundation footing, defaults to "SQUARE".
+    :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:`ABC_TYPE`,
+                     Available values can be found in :class:`ABCType`,
                      defaults to None.
-    :type abc_type:  ABC_TYPE | str
+    :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
+    :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.
+    :raises ValueError: Raised if an invalid footing ``shape`` is provided.
     """
-    msg = (f"{abc_type = } is not supported, Supported "
-           f"types are: {list(ABC_TYPE)}")
+    msg = (f"{abc_type=} is not supported, Supported "
+           f"types are: {list(ABCType)}")
 
     if abc_type is None:
         raise ValueError(msg)
 
     try:
-        abc_type = ABC_TYPE(str(abc_type).casefold())
+        abc_type = ABCType(str(abc_type).casefold())
     except ValueError as e:
         raise ValueError(msg) from e
 
-    msg = (f"{foundation_type = } is not supported, Supported "
+    msg = (f"{foundation_type=} is not supported, Supported "
            f"types are: {list(FoundationType)}")
 
     try:
@@ -183,23 +122,24 @@ def create_allowable_bearing_capacity(corrected_spt_n_value: float,
                                  length=length,
                                  eccentricity=eccentricity,
                                  ground_water_level=ground_water_level,
+                                 foundation_type=foundation_type,
                                  shape=shape)
     abc_classes = {
-        ABC_TYPE.BOWLES: {
+        ABCType.BOWLES: {
             FoundationType.PAD: BowlesABC4PadFoundation,
             FoundationType.MAT: BowlesABC4MatFoundation,
         },
-        ABC_TYPE.MEYERHOF: {
+        ABCType.MEYERHOF: {
             FoundationType.PAD: MeyerhofABC4PadFoundation,
             FoundationType.MAT: MeyerhofABC4MatFoundation,
         },
-        ABC_TYPE.TERZAGHI: {
+        ABCType.TERZAGHI: {
             FoundationType.PAD: TerzaghiABC4PadFoundation,
             FoundationType.MAT: TerzaghiABC4MatFoundation,
         }
     }
 
-    abc_class = abc_classes[abc_type][foundation_type]
+    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)

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/bearing_capacity/abc/cohl/bowles_abc.py

@@ -12,7 +12,7 @@ Classes
 from geolysis.foundation import FoundationSize
 from geolysis.utils import round_
 
-from . import AllowableBearingCapacity
+from ._core import AllowableBearingCapacity
 
 
 class BowlesABC4PadFoundation(AllowableBearingCapacity):

geolysis/bearing_capacity/abc/cohl/meyerhof_abc.py

@@ -12,7 +12,7 @@ Classes
 from geolysis.foundation import FoundationSize
 from geolysis.utils import round_
 
-from . import AllowableBearingCapacity
+from ._core import AllowableBearingCapacity
 
 
 class MeyerhofABC4PadFoundation(AllowableBearingCapacity):

geolysis/bearing_capacity/abc/cohl/terzaghi_abc.py

@@ -12,7 +12,7 @@ Classes
 from geolysis.foundation import FoundationSize
 from geolysis.utils import round_
 
-from . import AllowableBearingCapacity
+from ._core import AllowableBearingCapacity
 
 
 class TerzaghiABC4PadFoundation(AllowableBearingCapacity):

geolysis/bearing_capacity/ubc/__init__.py

@@ -7,7 +7,7 @@ Enum
     :toctree: _autosummary
     :nosignatures:
 
-    UBC_TYPE
+    UBCType
 
 Functions
 =========
@@ -18,13 +18,19 @@ Functions
     create_ultimate_bearing_capacity
 """
 import enum
-from abc import ABC, abstractmethod
 from typing import Optional
 
-from geolysis.foundation import FoundationSize, Shape, create_foundation
-from geolysis.utils import arctan, enum_repr, tan, round_, validators
+from geolysis.foundation import Shape, create_foundation
+from geolysis.utils import enum_repr
 
-__all__ = ["UltimateBearingCapacity",
+from ._core import UltimateBearingCapacity
+from .hansen_ubc import HansenUltimateBearingCapacity
+from .terzaghi_ubc import (TerzaghiUBC4CircularFooting,
+                           TerzaghiUBC4RectangularFooting,
+                           TerzaghiUBC4SquareFooting, TerzaghiUBC4StripFooting)
+from .vesic_ubc import VesicUltimateBearingCapacity
+
+__all__ = ["UBCType",
            "TerzaghiUBC4StripFooting",
            "TerzaghiUBC4CircularFooting",
            "TerzaghiUBC4RectangularFooting",
@@ -34,193 +40,8 @@ __all__ = ["UltimateBearingCapacity",
            "create_ultimate_bearing_capacity"]
 
 
-class UltimateBearingCapacity(ABC):
-    def __init__(self, friction_angle: float,
-                 cohesion: float,
-                 moist_unit_wgt: float,
-                 foundation_size: FoundationSize,
-                 load_angle=0.0,
-                 apply_local_shear=False) -> None:
-        r"""
-        :param friction_angle: Internal angle of friction for general shear 
-                               failure (degrees).
-        :type friction_angle: float
-        
-        :param cohesion: Cohesion of soil (:math:`kPa`).
-        :type cohesion: float
-
-        :param moist_unit_wgt: Moist unit weight of soil (:math:`kN/m^3`).
-        :type moist_unit_wgt: float
-
-        :param foundation_size: Size of the foundation.
-        :type foundation_size: FoundationSize
-
-        :param load_angle: Inclination of the applied load with the  vertical 
-                           (:math:`\alpha^{\circ}`), defaults to 0.0.
-        :type load_angle: float, optional
-
-        :param apply_local_shear: Indicate whether bearing capacity failure is
-                                  general shear or local shear failure,
-                                  defaults to False.
-        :type apply_local_shear: bool, optional
-        """
-        self.friction_angle = friction_angle
-        self.cohesion = cohesion
-        self.moist_unit_wgt = moist_unit_wgt
-        self.load_angle = load_angle
-        self.foundation_size = foundation_size
-        self.apply_local_shear = apply_local_shear
-
-    @property
-    def friction_angle(self) -> float:
-        """Return friction angle for local shear in the case of local shear
-        failure or general shear in the case of general shear failure.
-        """
-        if self.apply_local_shear:
-            return arctan((2 / 3) * tan(self._friction_angle))
-        return self._friction_angle
-
-    @friction_angle.setter
-    @validators.ge(0.0)
-    def friction_angle(self, val: float):
-        self._friction_angle = val
-
-    @property
-    def cohesion(self) -> float:
-        """Return cohesion for local shear in the case of local shear failure
-        or general shear in the case of general shear failure.
-        """
-        if self.apply_local_shear:
-            return (2.0 / 3.0) * self._cohesion
-        return self._cohesion
-
-    @cohesion.setter
-    @validators.ge(0.0)
-    def cohesion(self, val: float):
-        self._cohesion = val
-
-    @property
-    def moist_unit_wgt(self) -> float:
-        return self._moist_unit_wgt
-
-    @moist_unit_wgt.setter
-    @validators.gt(0.0)
-    def moist_unit_wgt(self, val: float):
-        self._moist_unit_wgt = val
-
-    @property
-    def load_angle(self) -> float:
-        return self._load_angle
-
-    @load_angle.setter
-    @validators.le(90.0)
-    @validators.ge(0.0)
-    def load_angle(self, val: float):
-        self._load_angle = val
-
-    @property
-    def s_c(self) -> float:
-        return 1.0
-
-    @property
-    def s_q(self) -> float:
-        return 1.0
-
-    @property
-    def s_gamma(self) -> float:
-        return 1.0
-
-    @property
-    def d_c(self) -> float:
-        return 1.0
-
-    @property
-    def d_q(self) -> float:
-        return 1.0
-
-    @property
-    def d_gamma(self) -> float:
-        return 1.0
-
-    @property
-    def i_c(self) -> float:
-        return 1.0
-
-    @property
-    def i_q(self) -> float:
-        return 1.0
-
-    @property
-    def i_gamma(self) -> float:
-        return 1.0
-
-    def _cohesion_term(self, coef: float = 1.0) -> float:
-        return coef * self.cohesion * self.n_c * self.s_c * self.d_c * self.i_c
-
-    def _surcharge_term(self) -> float:
-        depth = self.foundation_size.depth
-        water_level = self.foundation_size.ground_water_level
-
-        if water_level is None:
-            water_corr = 1.0  # water correction
-        else:
-            # water level above the base of the foundation
-            a = max(depth - water_level, 0.0)
-            water_corr = min(1 - 0.5 * a / depth, 1)
-
-        # effective overburden pressure (surcharge)
-        eop = self.moist_unit_wgt * depth
-        return eop * self.n_q * self.s_q * self.d_q * self.i_q * water_corr
-
-    def _embedment_term(self, coef: float = 0.5) -> float:
-        depth = self.foundation_size.depth
-        width = self.foundation_size.effective_width
-        water_level = self.foundation_size.ground_water_level
-
-        if water_level is None:
-            # water correction
-            water_corr = 1.0
-        else:
-            #: b -> water level below the base of the foundation
-            b = max(water_level - depth, 0)
-            water_corr = min(0.5 + 0.5 * b / width, 1)
-
-        return (coef * self.moist_unit_wgt * width * self.n_gamma
-                * self.s_gamma * self.d_gamma * self.i_gamma * water_corr)
-
-    @round_
-    def bearing_capacity(self):
-        """Calculates the ultimate bearing capacity."""
-        return (self._cohesion_term(1.0)
-                + self._surcharge_term()
-                + self._embedment_term(0.5))
-
-    @property
-    @abstractmethod
-    def n_c(self) -> float:
-        ...
-
-    @property
-    @abstractmethod
-    def n_q(self) -> float:
-        ...
-
-    @property
-    @abstractmethod
-    def n_gamma(self) -> float:
-        ...
-
-
-from .hansen_ubc import HansenUltimateBearingCapacity
-from .terzaghi_ubc import (TerzaghiUBC4CircularFooting,
-                           TerzaghiUBC4RectangularFooting,
-                           TerzaghiUBC4SquareFooting,
-                           TerzaghiUBC4StripFooting)
-from .vesic_ubc import VesicUltimateBearingCapacity
-
-
 @enum_repr
-class UBC_TYPE(enum.StrEnum):
+class UBCType(enum.StrEnum):
     """Enumeration of available ultimate bearing capacity types."""
     HANSEN = enum.auto()
     TERZAGHI = enum.auto()
@@ -236,45 +57,42 @@ def create_ultimate_bearing_capacity(friction_angle: float,
                                      eccentricity: float = 0.0,
                                      ground_water_level: Optional[
                                          float] = None,
-                                     shape: Shape | str = Shape.SQUARE,
                                      load_angle=0.0,
                                      apply_local_shear=False,
-                                     ubc_type: Optional[UBC_TYPE | str] = None,
+                                     shape: Shape | str = Shape.SQUARE,
+                                     ubc_type: Optional[UBCType | str] = None,
                                      ) -> UltimateBearingCapacity:
     r"""A factory function that encapsulate the creation of ultimate bearing
     capacity.
 
     :param friction_angle: Internal angle of friction for general shear
-                           failure. (degree)
+                           failure (degree).
     :type friction_angle: float
 
-    :param cohesion: Cohesion of soil. (kPa)
+    :param cohesion: Cohesion of soil (:math:`kPa`).
     :type cohesion: float
 
-    :param moist_unit_wgt: Moist unit weight of soil. (:math:`kN/m^3`)
+    :param moist_unit_wgt: Moist unit weight of soil (:math:`kN/m^3`).
     :type moist_unit_wgt: float
 
-    :param depth: Depth of foundation. (m)
+    :param depth: Depth of foundation (m).
     :type depth: float
 
-    :param width: Width of foundation footing. (m)
+    :param width: Width of foundation footing (m).
     :type width: float
 
-    :param length: Length of foundation footing. (m)
+    :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
+                         defaults to 0.0 (m). This means that the foundation
                          load aligns with the center of gravity of the
-                         foundation footing. (m)
+                         foundation footing.
     :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: Shape | str, optional
+    :param ground_water_level: Depth of water below ground level (m).
+    :type ground_water_level: float, optional
 
     :param load_angle: Inclination of the applied load with the  vertical
                        (:math:`\alpha^{\circ}`), defaults to 0.0.
@@ -285,28 +103,33 @@ def create_ultimate_bearing_capacity(friction_angle: float,
                               False.
     :type apply_local_shear: bool, optional
 
+    :param shape: Shape of foundation footing, defaults to
+                  :attr:`~geolysis.foundation.Shape.SQUARE`.
+    :type shape: Shape | str, optional
+
     :param ubc_type: Type of allowable bearing capacity calculation to apply.
-                     Available values are: "HANSEN", "TERZAGHI", "VESIC".
+                     Available values are: :attr:`~UBCType.HANSEN`,
+                     :attr:`~UBCType.TERZAGHI`, and :attr:`~UBCType.VESIC`
                      defaults to None.
-    :type ubc_type:  UBC_TYPE | str, optional
+    :type ubc_type:  UBCType | str, optional
 
     :raises ValueError: Raised if ubc_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"{ubc_type = } is not supported, Supported "
-           f"types are: {list(UBC_TYPE)}")
+    msg = (f"{ubc_type=} is not supported, Supported "
+           f"types are: {list(UBCType)}")
 
     if ubc_type is None:
         raise ValueError(msg)
 
     try:
-        ubc_type = UBC_TYPE(str(ubc_type).casefold())
+        ubc_type = UBCType(str(ubc_type).casefold())
     except ValueError as e:
         raise ValueError(msg) from e
 
-    # exception from create_foundation will automaatically propagate
+    # exception from create_foundation will automatically propagate
     # no need to catch and handle it.
     fnd_size = create_foundation(depth=depth,
                                  width=width,
@@ -315,15 +138,15 @@ def create_ultimate_bearing_capacity(friction_angle: float,
                                  ground_water_level=ground_water_level,
                                  shape=shape)
     ubc_classes = {
-        UBC_TYPE.HANSEN: HansenUltimateBearingCapacity,
-        UBC_TYPE.TERZAGHI: {Shape.STRIP: TerzaghiUBC4StripFooting,
-                            Shape.CIRCLE: TerzaghiUBC4CircularFooting,
-                            Shape.SQUARE: TerzaghiUBC4SquareFooting,
-                            Shape.RECTANGLE: TerzaghiUBC4RectangularFooting},
-        UBC_TYPE.VESIC: VesicUltimateBearingCapacity,
+        UBCType.HANSEN: HansenUltimateBearingCapacity,
+        UBCType.TERZAGHI: {Shape.STRIP: TerzaghiUBC4StripFooting,
+                           Shape.CIRCLE: TerzaghiUBC4CircularFooting,
+                           Shape.SQUARE: TerzaghiUBC4SquareFooting,
+                           Shape.RECTANGLE: TerzaghiUBC4RectangularFooting},
+        UBCType.VESIC: VesicUltimateBearingCapacity,
     }
 
-    if ubc_type == UBC_TYPE.TERZAGHI:
+    if ubc_type == UBCType.TERZAGHI:
         ubc_class = ubc_classes[ubc_type][fnd_size.footing_shape]
     else:
         ubc_class = ubc_classes[ubc_type]