geolysis 0.4.3__py3-none-any.whl → 0.4.5__py3-none-any.whl

geolysis/foundation.py

@@ -35,7 +35,7 @@ import enum
 from abc import ABC, abstractmethod
 from typing import Optional, TypeVar
 
-from geolysis.utils import inf, enum_repr, isclose, validators
+from .utils import enum_repr, inf, isclose, validators
 
 __all__ = ["create_foundation",
            "FoundationSize",
@@ -66,7 +66,7 @@ class FoundationType(enum.StrEnum):
 
 
 class FootingSize(ABC):
-    SHAPE: Shape
+    _SHAPE: Shape
 
     @property
     @abstractmethod
@@ -88,13 +88,14 @@ class FootingSize(ABC):
 
     @property
     def shape(self) -> Shape:
-        return self.SHAPE
+        """Return the shape of the foundation footing."""
+        return self._SHAPE
 
 
 class StripFooting(FootingSize):
     """A class representation of strip footing."""
 
-    SHAPE = Shape.STRIP
+    _SHAPE = Shape.STRIP
 
     def __init__(self, width: float, length: float = inf) -> None:
         """
@@ -109,6 +110,7 @@ class StripFooting(FootingSize):
 
     @property
     def width(self) -> float:
+        """Width of foundation footing (m)."""
         return self._width
 
     @width.setter
@@ -118,6 +120,7 @@ class StripFooting(FootingSize):
 
     @property
     def length(self) -> float:
+        """Length of foundation footing (m)."""
         return self._length
 
     @length.setter
@@ -136,7 +139,7 @@ class CircularFooting(FootingSize):
         square and rectangular footing follow.
     """
 
-    SHAPE = Shape.CIRCLE
+    _SHAPE = Shape.CIRCLE
 
     def __init__(self, diameter: float):
         """
@@ -146,6 +149,7 @@ class CircularFooting(FootingSize):
 
     @property
     def diameter(self) -> float:
+        """Diameter of foundation footing (m)."""
         return self._diameter
 
     @diameter.setter
@@ -155,6 +159,7 @@ class CircularFooting(FootingSize):
 
     @property
     def width(self):
+        """Diameter of foundation footing (m)."""
         return self.diameter
 
     @width.setter
@@ -163,6 +168,7 @@ class CircularFooting(FootingSize):
 
     @property
     def length(self):
+        """Diameter of foundation footing (m)."""
         return self.diameter
 
     @length.setter
@@ -173,7 +179,7 @@ class CircularFooting(FootingSize):
 class SquareFooting(FootingSize):
     """A class representation of square footing."""
 
-    SHAPE = Shape.SQUARE
+    _SHAPE = Shape.SQUARE
 
     def __init__(self, width: float):
         """
@@ -183,6 +189,7 @@ class SquareFooting(FootingSize):
 
     @property
     def width(self):
+        """Width of foundation footing (m)."""
         return self._width
 
     @width.setter
@@ -192,6 +199,7 @@ class SquareFooting(FootingSize):
 
     @property
     def length(self):
+        """Width of foundation footing (m)."""
         return self.width
 
     @length.setter
@@ -202,7 +210,7 @@ class SquareFooting(FootingSize):
 class RectangularFooting(FootingSize):
     """A class representation of rectangular footing."""
 
-    SHAPE = Shape.RECTANGLE
+    _SHAPE = Shape.RECTANGLE
 
     def __init__(self, width: float, length: float):
         """
@@ -217,6 +225,7 @@ class RectangularFooting(FootingSize):
 
     @property
     def width(self) -> float:
+        """Width of foundation footing (m)."""
         return self._width
 
     @width.setter
@@ -226,6 +235,7 @@ class RectangularFooting(FootingSize):
 
     @property
     def length(self) -> float:
+        """Length of foundation footing (m)."""
         return self._length
 
     @length.setter
@@ -240,7 +250,8 @@ class FoundationSize:
     def __init__(self, depth: float,
                  footing_size: FootingSize,
                  eccentricity: float = 0.0,
-                 ground_water_level: Optional[float] = None) -> None:
+                 ground_water_level: Optional[float] = None,
+                 foundation_type: FoundationType = FoundationType.PAD) -> None:
         """
         :param depth: Depth of foundation (m).
         :type depth: float
@@ -258,14 +269,21 @@ class FoundationSize:
         :param ground_water_level: Depth of the water below ground level (m),
                                    defaults to inf.
         :type ground_water_level: float, optional
+
+        :param foundation_type: Type of foundation, defaults to
+                                :attr:`FoundationType.PAD`
+        :type foundation_type: FoundationType, optional
         """
         self.depth = depth
         self.footing_size = footing_size
         self.eccentricity = eccentricity
+
         self._ground_water_level = ground_water_level
+        self._foundation_type = foundation_type
 
     @property
     def depth(self) -> float:
+        """Depth of foundation (m)."""
         return self._depth
 
     @depth.setter
@@ -274,7 +292,8 @@ class FoundationSize:
         self._depth = val
 
     @property
-    def width(self):
+    def width(self) -> float:
+        """Width of foundation footing (m)."""
         return self.footing_size.width
 
     @width.setter
@@ -282,7 +301,8 @@ class FoundationSize:
         self.footing_size.width = val
 
     @property
-    def length(self):
+    def length(self) -> float:
+        """Length of foundation footing (m)."""
         return self.footing_size.length
 
     @length.setter
@@ -290,11 +310,15 @@ class FoundationSize:
         self.footing_size.length = val
 
     @property
-    def footing_shape(self):
+    def footing_shape(self) -> Shape:
+        """Shape of foundation footing."""
         return self.footing_size.shape
 
     @property
     def eccentricity(self) -> float:
+        """The deviation of the foundation load from the center of gravity of
+        the foundation footing.
+        """
         return self._eccentricity
 
     @eccentricity.setter
@@ -304,6 +328,7 @@ class FoundationSize:
 
     @property
     def ground_water_level(self) -> Optional[float]:
+        """Depth of the water below ground level (m)."""
         return self._ground_water_level
 
     @ground_water_level.setter
@@ -311,16 +336,19 @@ class FoundationSize:
     def ground_water_level(self, val: float) -> None:
         self._ground_water_level = val
 
+    @property
+    def foundation_type(self) -> FoundationType:
+        """Type of foundation."""
+        return self._foundation_type
+
     @property
     def effective_width(self) -> float:
         """Returns the effective width of the foundation footing."""
         return self.width - 2.0 * self.eccentricity
 
     def footing_params(self) -> tuple[float, float, Shape]:
-        """Returns the ``width``, ``length``, and ``shape`` of the
-        foundation footing.
-
-        .. note:: "width" is the effective width of the foundation footing.
+        """Returns the :attr:`effective_width`, :attr:`length`, and
+        :attr:`footing_shape` of the foundation footing.
         """
         width, length, shape = self.effective_width, self.length, self.footing_shape
 
@@ -335,6 +363,7 @@ def create_foundation(depth: float,
                       length: Optional[float] = None,
                       eccentricity: float = 0.0,
                       ground_water_level: Optional[float] = None,
+                      foundation_type: FoundationType = FoundationType.PAD,
                       shape: Shape | str = Shape.SQUARE) -> FoundationSize:
     """A factory function that encapsulate the creation of a foundation.
 
@@ -359,8 +388,12 @@ def create_foundation(depth: float,
                                defaults to None.
     :type ground_water_level: float, optional
 
+    :param foundation_type: Type of foundation footing, defaults to
+                            FoundationType.PAD.
+    :type foundation_type: FoundationType, optional
+
     :param shape: Shape of foundation footing, defaults to :class:`Shape.SQUARE`
-    :type shape: Shape | str
+    :type shape: Shape | str, optional
 
     :raises ValueError: Raised when length is not provided for a rectangular
                         footing.
@@ -371,7 +404,7 @@ def create_foundation(depth: float,
     try:
         shape = Shape(shape)
     except ValueError as e:
-        msg = (f"{shape = } is not supported, Supported "
+        msg = (f"{shape=} is not supported, Supported "
                f"types are: {list(Shape)}")
 
         raise ValueError(msg) from e
@@ -390,4 +423,5 @@ def create_foundation(depth: float,
     return FoundationSize(depth=depth,
                           eccentricity=eccentricity,
                           ground_water_level=ground_water_level,
+                          foundation_type=foundation_type,
                           footing_size=footing_size)

geolysis/soil_classifier.py

@@ -15,7 +15,7 @@ Enums
     :toctree: _autosummary
     :nosignatures:
 
-    CLF_TYPE
+    ClfType
     USCSSymbol
     AASHTOSymbol
 
@@ -40,12 +40,11 @@ Functions
 """
 import enum
 from abc import abstractmethod
-from typing import Protocol
-from typing import NamedTuple, Optional, Sequence
+from typing import NamedTuple, Optional, Protocol, Sequence
 
-from geolysis.utils import enum_repr, isclose, round_, validators
+from .utils import enum_repr, isclose, round_, validators
 
-__all__ = ["CLF_TYPE",
+__all__ = ["ClfType",
            "AtterbergLimits",
            "PSD",
            "AASHTO",
@@ -163,6 +162,7 @@ class AtterbergLimits:
 
     @property
     def liquid_limit(self) -> float:
+        """Water content beyond which soils flows under their own weight (%)."""
         return self._liquid_limit
 
     @liquid_limit.setter
@@ -172,6 +172,7 @@ class AtterbergLimits:
 
     @property
     def plastic_limit(self) -> float:
+        """Water content at which plastic deformation can be initiated (%)."""
         return self._plastic_limit
 
     @plastic_limit.setter
@@ -196,9 +197,7 @@ class AtterbergLimits:
 
     @property
     def fine_material_type(self) -> USCSSymbol:
-        """
-        Checks whether the soil is either clay or silt.
-        """
+        """Checks whether the soil is either clay or silt."""
         return USCSSymbol.CLAY if self.above_A_LINE() else USCSSymbol.SILT
 
     def above_A_LINE(self) -> bool:
@@ -440,6 +439,7 @@ class AASHTO:
 
     @property
     def fines(self) -> float:
+        """Percentage of fines in soil sample (%)."""
         return self._fines
 
     @fines.setter
@@ -683,18 +683,18 @@ class USCS:
                 f"{coarse_material_type}{fine_material_type}")
 
 
+class SoilClassifier(Protocol):
+    @abstractmethod
+    def classify(self) -> SoilClf: ...
+
+
 @enum_repr
-class CLF_TYPE(enum.StrEnum):
+class ClfType(enum.StrEnum):
     """Enumeration of soil classification types."""
     AASHTO = enum.auto()
     USCS = enum.auto()
 
 
-class SoilClassifier(Protocol):
-    @abstractmethod
-    def classify(self) -> SoilClf: ...
-
-
 def create_soil_classifier(liquid_limit: float,
                            plastic_limit: float,
                            fines: float,
@@ -702,7 +702,7 @@ def create_soil_classifier(liquid_limit: float,
                            d_10: float = 0, d_30: float = 0, d_60: float = 0,
                            add_group_idx: bool = True,
                            organic: bool = False,
-                           clf_type: Optional[CLF_TYPE | str] = None
+                           clf_type: Optional[ClfType | str] = None
                            ) -> SoilClassifier:
     """ A factory function that encapsulates the creation of a soil classifier.
 
@@ -722,17 +722,18 @@ def create_soil_classifier(liquid_limit: float,
                   soil sample passing through No. 200 sieve (0.075mm).
     :type fines: float
 
-    :param sand: Percentage of sand in soil sample (%).
-    :type sand: float
+    :param sand: Percentage of sand in soil sample (%). This is optional for
+                 :class:`AASHTO` classification.
+    :type sand: float, optional
 
     :param d_10: Diameter at which 10% of the soil by weight is finer.
-    :type d_10: float
+    :type d_10: float, optional
 
     :param d_30: Diameter at which 30% of the soil by weight is finer.
-    :type d_30: float
+    :type d_30: float, optional
 
     :param d_60: Diameter at which 60% of the soil by weight is finer.
-    :type d_60: float
+    :type d_60: float, optional
 
     :param add_group_idx: Used to indicate whether the group index should
                           be added to the classification or not, defaults to
@@ -744,28 +745,28 @@ def create_soil_classifier(liquid_limit: float,
 
     :param clf_type: Used to indicate which type of soil classifier should be
                      used, defaults to None.
-    :type clf_type: CLF_TYPE | str
+    :type clf_type: ClfType | str
 
     :raises ValueError: Raises ValueError if ``clf_type`` is  not supported or
                         None
     :raises ValueError: Raises ValueError if ``sand`` is not provided for
                         :class:`USCS` classification.
     """
-    msg = (f"{clf_type = } is not supported, Supported "
-           f"types are: {list(CLF_TYPE)}")
+    msg = (f"{clf_type=} is not supported, Supported "
+           f"types are: {list(ClfType)}")
 
     if clf_type is None:
         raise ValueError(msg)
 
     try:
-        clf_type = CLF_TYPE(str(clf_type).casefold())
+        clf_type = ClfType(str(clf_type).casefold())
     except ValueError as e:
         raise ValueError(msg) from e
 
     atterberg_lmts = AtterbergLimits(liquid_limit=liquid_limit,
                                      plastic_limit=plastic_limit)
 
-    if clf_type == CLF_TYPE.AASHTO:
+    if clf_type == ClfType.AASHTO:
         clf = AASHTO(atterberg_limits=atterberg_lmts,
                      fines=fines,
                      add_group_idx=add_group_idx)