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

geolysis/__init__.py

@@ -1,3 +1 @@
-from . import foundation, soil_classifier, spt, utils
-
-__version__ = "0.4.2"
+__version__ = "0.4.3"

geolysis/foundation.py

@@ -1,42 +1,55 @@
-import enum
-from abc import abstractmethod
-from typing import Optional, Protocol, TypeVar
+""" Basic foundation module.
 
-from geolysis import validators
-from geolysis.utils import inf
+Enums
+=====
 
-__all__ = ["create_foundation", "FoundationSize", "Shape", "StripFooting",
-           "CircularFooting", "SquareFooting", "RectangularFooting"]
+.. autosummary::
+    :toctree: _autosummary
+    :nosignatures:
 
-T = TypeVar("T")
+    Shape
+    FoundationType
+
+Classes
+=======
+
+.. autosummary::
+    :toctree: _autosummary
 
+    StripFooting
+    CircularFooting
+    SquareFooting
+    RectangularFooting
+    FoundationSize
 
-class _Field:
-    """A field that references another field."""
+Functions
+=========
 
-    def __init__(self, *, ref_attr: str, ref_obj: Optional[str] = None,
-                 doc: Optional[str] = None):
-        self.ref_attr = ref_attr
-        self.ref_obj = ref_obj
-        self.__doc__ = doc
+.. autosummary::
+    :toctree: _autosummary
 
-    def __get__(self, obj, objtype=None) -> T:
-        if self.ref_obj is not None:
-            ref_obj = getattr(obj, self.ref_obj)
-            return getattr(ref_obj, self.ref_attr)
-        return getattr(obj, self.ref_attr)
+    create_foundation
+"""
 
-    def __set__(self, obj, value) -> None:
-        if self.ref_obj is not None:
-            ref_obj = getattr(obj, self.ref_obj)
-            setattr(ref_obj, self.ref_attr, value)
-        else:
-            setattr(obj, self.ref_attr, value)
+import enum
+from abc import ABC, abstractmethod
+from typing import Optional, TypeVar
+
+from geolysis.utils import inf, enum_repr, isclose, validators
 
-    def __set_name__(self, objtype, property_name) -> None:
-        self.property_name = property_name
+__all__ = ["create_foundation",
+           "FoundationSize",
+           "FoundationType",
+           "Shape",
+           "StripFooting",
+           "CircularFooting",
+           "SquareFooting",
+           "RectangularFooting"]
+
+T = TypeVar("T")
 
 
+@enum_repr
 class Shape(enum.StrEnum):
     """Enumeration of foundation shapes."""
     STRIP = enum.auto()
@@ -45,34 +58,54 @@ class Shape(enum.StrEnum):
     RECTANGLE = enum.auto()
 
 
-class FootingSize(Protocol):
+@enum_repr
+class FoundationType(enum.StrEnum):
+    """Enumeration of foundation types."""
+    PAD = ISOLATED = enum.auto()
+    MAT = RAFT = enum.auto()
+
+
+class FootingSize(ABC):
+    SHAPE: Shape
+
     @property
     @abstractmethod
-    def width(self) -> float: ...
+    def width(self) -> float:
+        raise NotImplementedError
+
+    @width.setter
+    def width(self, value: float):
+        raise NotImplementedError
 
     @property
     @abstractmethod
-    def length(self) -> float: ...
+    def length(self) -> float:
+        raise NotImplementedError
+
+    @length.setter
+    def length(self, value: float):
+        raise NotImplementedError
 
     @property
-    @abstractmethod
-    def shape(self) -> Shape: ...
+    def shape(self) -> Shape:
+        return self.SHAPE
 
 
-class StripFooting:
+class StripFooting(FootingSize):
     """A class representation of strip footing."""
 
+    SHAPE = Shape.STRIP
+
     def __init__(self, width: float, length: float = inf) -> None:
         """
-        :param width: Width of foundation footing. (m)
+        :param width: Width of foundation footing (m).
         :type width: float
 
-        :param float length: Length of foundation footing, defaults to inf. (m)
+        :param float length: Length of foundation footing, defaults to inf (m).
         :type length: float
         """
         self.width = width
         self.length = length
-        self._shape = Shape.STRIP
 
     @property
     def width(self) -> float:
@@ -80,7 +113,7 @@ class StripFooting:
 
     @width.setter
     @validators.gt(0.0)
-    def width(self, val):
+    def width(self, val: float):
         self._width = val
 
     @property
@@ -89,15 +122,11 @@ class StripFooting:
 
     @length.setter
     @validators.ge(0.0)
-    def length(self, val):
+    def length(self, val: float):
         self._length = val
 
-    @property
-    def shape(self) -> Shape:
-        return self._shape
-
 
-class CircularFooting:
+class CircularFooting(FootingSize):
     """A class representation of circular footing.
 
     .. note::
@@ -107,19 +136,13 @@ class CircularFooting:
         square and rectangular footing follow.
     """
 
-    _doc = "Refers to the diameter of the circular footing."
-
-    width = _Field(ref_attr="diameter", doc=_doc)
-    length = _Field(ref_attr="diameter", doc=_doc)
-
-    del _doc
+    SHAPE = Shape.CIRCLE
 
     def __init__(self, diameter: float):
         """
-        :param float diameter: Diameter of foundation footing. (m)
+        :param float diameter: Diameter of foundation footing (m).
         """
         self.diameter = diameter
-        self._shape = Shape.CIRCLE
 
     @property
     def diameter(self) -> float:
@@ -127,26 +150,36 @@ class CircularFooting:
 
     @diameter.setter
     @validators.gt(0.0)
-    def diameter(self, val):
+    def diameter(self, val: float):
         self._diameter = val
 
     @property
-    def shape(self) -> Shape:
-        return self._shape
+    def width(self):
+        return self.diameter
+
+    @width.setter
+    def width(self, val: float):
+        self.diameter = val
+
+    @property
+    def length(self):
+        return self.diameter
+
+    @length.setter
+    def length(self, val: float):
+        self.diameter = val
 
 
-class SquareFooting:
+class SquareFooting(FootingSize):
     """A class representation of square footing."""
 
-    length = _Field(ref_attr="width",
-                    doc="Refers to the width of the square footing.")
+    SHAPE = Shape.SQUARE
 
     def __init__(self, width: float):
         """
-        :param float width: Width of foundation footing. (m)
+        :param float width: Width of foundation footing (m).
         """
         self.width = width
-        self._shape = Shape.SQUARE
 
     @property
     def width(self):
@@ -158,24 +191,29 @@ class SquareFooting:
         self._width = val
 
     @property
-    def shape(self):
-        return self._shape
+    def length(self):
+        return self.width
+
+    @length.setter
+    def length(self, val):
+        self.width = val
 
 
-class RectangularFooting:
+class RectangularFooting(FootingSize):
     """A class representation of rectangular footing."""
 
+    SHAPE = Shape.RECTANGLE
+
     def __init__(self, width: float, length: 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
         """
         self.width = width
         self.length = length
-        self._shape = Shape.RECTANGLE
 
     @property
     def width(self) -> float:
@@ -195,26 +233,16 @@ class RectangularFooting:
     def length(self, val):
         self._length = val
 
-    @property
-    def shape(self) -> Shape:
-        return self._shape
-
 
 class FoundationSize:
     """A simple class representing a foundation structure."""
 
-    width = _Field(ref_attr="width", ref_obj="footing_size",
-                   doc="Refers to the width of foundation footing.")
-    length = _Field(ref_attr="length", ref_obj="footing_size",
-                    doc="Refers to the length of foundation footing.")
-    footing_shape = _Field(ref_attr="shape", ref_obj="footing_size",
-                           doc="Refers to the shape of foundation footing.")
-
-    def __init__(self, depth: float, footing_size: FootingSize,
+    def __init__(self, depth: float,
+                 footing_size: FootingSize,
                  eccentricity: float = 0.0,
-                 ground_water_level: float = inf) -> None:
+                 ground_water_level: Optional[float] = None) -> None:
         """
-        :param depth: Depth of foundation. (m)
+        :param depth: Depth of foundation (m).
         :type depth: float
 
         :param footing_size: Represents the size of the foundation footing.
@@ -224,7 +252,7 @@ class FoundationSize:
                              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)
+                             foundation footing (m).
         :type eccentricity: float, optional
 
         :param ground_water_level: Depth of the water below ground level (m),
@@ -234,7 +262,7 @@ class FoundationSize:
         self.depth = depth
         self.footing_size = footing_size
         self.eccentricity = eccentricity
-        self.ground_water_level = ground_water_level
+        self._ground_water_level = ground_water_level
 
     @property
     def depth(self) -> float:
@@ -245,6 +273,26 @@ class FoundationSize:
     def depth(self, val: float) -> None:
         self._depth = val
 
+    @property
+    def width(self):
+        return self.footing_size.width
+
+    @width.setter
+    def width(self, val: float):
+        self.footing_size.width = val
+
+    @property
+    def length(self):
+        return self.footing_size.length
+
+    @length.setter
+    def length(self, val: float):
+        self.footing_size.length = val
+
+    @property
+    def footing_shape(self):
+        return self.footing_size.shape
+
     @property
     def eccentricity(self) -> float:
         return self._eccentricity
@@ -255,7 +303,7 @@ class FoundationSize:
         self._eccentricity = val
 
     @property
-    def ground_water_level(self) -> float:
+    def ground_water_level(self) -> Optional[float]:
         return self._ground_water_level
 
     @ground_water_level.setter
@@ -268,33 +316,47 @@ class FoundationSize:
         """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.
+        """
+        width, length, shape = self.effective_width, self.length, self.footing_shape
+
+        if not isclose(width, length) and shape != Shape.STRIP:
+            shape = Shape.RECTANGLE
 
-def create_foundation(depth: float, width: float,
+        return width, length, shape
+
+
+def create_foundation(depth: float,
+                      width: float,
                       length: Optional[float] = None,
                       eccentricity: float = 0.0,
-                      ground_water_level: float = inf,
+                      ground_water_level: Optional[float] = None,
                       shape: Shape | str = Shape.SQUARE) -> FoundationSize:
     """A factory function that encapsulate the creation of a foundation.
 
-    :param depth: Depth of foundation. (m)
+    :param depth: Depth of foundation (m).
     :type depth: float
 
     :param width: Width of foundation footing. In the case of a circular
-                  footing, it refers to the footing diameter. (m)
+                  footing, it refers to the footing diameter (m).
     :type width: float
 
-    :param length: Length of foundation footing, defaults to None. (m)
+    :param length: Length of foundation footing (m), defaults to None.
     :type length: float, optional
 
     :param eccentricity: The deviation of the foundation load from the
-                         center of gravity of the foundation footing,
+                         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. (m)
+                         foundation footing .
     :type eccentricity: float, optional
 
     :param ground_water_level: Depth of the water below ground level (m),
-                               defaults to inf.
+                               defaults to None.
     :type ground_water_level: float, optional
 
     :param shape: Shape of foundation footing, defaults to :class:`Shape.SQUARE`
@@ -302,11 +364,17 @@ def create_foundation(depth: float, width: float,
 
     :raises ValueError: Raised when length is not provided for a rectangular
                         footing.
-    :raises TypeError: Raised if an invalid footing shape is provided.
+    :raises ValueError: Raised if an invalid footing shape is provided.
     """
+    shape = str(shape).casefold()
+
+    try:
+        shape = Shape(shape)
+    except ValueError as e:
+        msg = (f"{shape = } is not supported, Supported "
+               f"types are: {list(Shape)}")
 
-    if isinstance(shape, str):
-        shape = Shape(shape.casefold())
+        raise ValueError(msg) from e
 
     if shape is Shape.STRIP:
         footing_size = StripFooting(width=width)
@@ -314,13 +382,12 @@ def create_foundation(depth: float, width: float,
         footing_size = SquareFooting(width=width)
     elif shape is Shape.CIRCLE:
         footing_size = CircularFooting(diameter=width)
-    elif shape is Shape.RECTANGLE:
+    else:  # RECTANGLE
         if not length:
             raise ValueError("Length of footing must be provided.")
         footing_size = RectangularFooting(width=width, length=length)
-    else:
-        raise TypeError(f"shape {shape} is not supported.")
 
-    return FoundationSize(depth=depth, eccentricity=eccentricity,
+    return FoundationSize(depth=depth,
+                          eccentricity=eccentricity,
                           ground_water_level=ground_water_level,
                           footing_size=footing_size)