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

geolysis/soil_classifier.py

@@ -1,53 +1,73 @@
-import enum
-from abc import abstractmethod
-from typing import Protocol
-from typing import NamedTuple, Optional, Sequence
+""" Soil classification module.
 
-from geolysis import validators
-from geolysis.utils import isclose, round_
+Exceptions
+==========
 
-__all__ = ["CLF_TYPE", "AtterbergLimits", "PSD", "AASHTO", "USCS",
-           "SizeDistribution", "create_soil_classifier"]
+.. autosummary::
+    :toctree: _autosummary
 
+    SizeDistError
 
-class SizeDistError(ZeroDivisionError):
-    """Exception raised when size distribution is not provided."""
-    pass
+Enums
+=====
 
+.. autosummary::
+    :toctree: _autosummary
+    :nosignatures:
 
-class SoilClf(NamedTuple):
-    symbol: str
-    description: str
+    CLF_TYPE
+    USCSSymbol
+    AASHTOSymbol
 
+Classes
+=======
 
-class SoilClassifier(Protocol):
+.. autosummary::
+    :toctree: _autosummary
 
-    @abstractmethod
-    def classify(self) -> SoilClf: ...
+    AtterbergLimits
+    PSD
+    AASHTO
+    USCS
 
+Functions
+=========
 
-class CLF_TYPE(enum.StrEnum):
-    """Enumeration of soil classification types."""
-    AASHTO = enum.auto()
-    USCS = enum.auto()
+.. autosummary::
+    :toctree: _autosummary
 
+    create_soil_classifier
+"""
+import enum
+from abc import abstractmethod
+from typing import NamedTuple, Optional, Protocol, Sequence
+
+from .utils import enum_repr, isclose, round_, validators
+
+__all__ = ["CLF_TYPE",
+           "AtterbergLimits",
+           "PSD",
+           "AASHTO",
+           "USCS",
+           "create_soil_classifier"]
+
+
+class SizeDistError(ZeroDivisionError):
+    """Exception raised when size distribution is not provided."""
 
-class _Clf(enum.Enum):
+
+@enum_repr
+class _Clf(tuple, enum.Enum):
 
     def __str__(self) -> str:
         return self.name
 
-    def __eq__(self, value: object) -> bool:
-        if isinstance(value, str):
-            return self.clf_symbol == value
-        return super().__eq__(value)
-
     @property
-    def clf_symbol(self) -> str:
+    def symbol(self) -> str:
         return self.value[0]
 
     @property
-    def clf_description(self) -> str:
+    def description(self) -> str:
         return self.value[1]
 
 
@@ -112,30 +132,31 @@ class AtterbergLimits:
     """
 
     class __A_LINE:
-        """The ``A-line`` is used to determine if a soil is clayey or silty.
-
-        .. math:: A = 0.73(LL - 20.0)
-        """
 
         def __get__(self, obj, objtype=None) -> float:
             return 0.73 * (obj.liquid_limit - 20.0)
 
+    #:  The ``A-line`` determines if a soil is clayey or silty.
+    #:  :math:`A = 0.73(LL - 20.0)`
     A_LINE = __A_LINE()
 
     def __init__(self, liquid_limit: float, plastic_limit: float):
         """
         :param liquid_limit: Water content beyond which soils flows under their 
-                             own weight. It can also be defined as the minimum 
-                             moisture content at which a soil flows upon 
-                             application of a very small shear force. (%)
+                             own weight (%). It can also be defined as the
+                             minimum moisture content at which a soil flows upon
+                             application of a very small shear force.
         :type liquid_limit: float
 
         :param plastic_limit: Water content at which plastic deformation can be 
-                              initiated. It is also the minimum water content at 
-                              which soil can be rolled into a thread 3mm thick. 
-                              (molded without breaking) (%)
+                              initiated (%). It is also the minimum water
+                              content at which soil can be rolled into a thread
+                              3mm thick. (molded without breaking)
         :type plastic_limit: float
         """
+        if liquid_limit < plastic_limit:
+            raise ValueError("liquid_limit cannot be less than plastic_limit")
+
         self.liquid_limit = liquid_limit
         self.plastic_limit = plastic_limit
 
@@ -166,6 +187,8 @@ class AtterbergLimits:
         It is also the numerical difference between the liquid limit and
         plastic limit of the soil.
 
+        :Equation:
+
         .. math:: PI = LL - PL
         """
         return self.liquid_limit - self.plastic_limit
@@ -199,6 +222,8 @@ class AtterbergLimits:
 
         :param float nmc: Moisture contents of the soil in natural condition.
 
+        :Equation:
+
         .. math:: I_l = \dfrac{w - PL}{PI} \cdot 100
         """
         return ((nmc - self.plastic_limit) / self.plasticity_index) * 100.0
@@ -220,20 +245,20 @@ class AtterbergLimits:
 
         :param float nmc: Moisture contents of the soil in natural condition.
 
+        :Equation:
+
         .. math:: I_c = \dfrac{LL - w}{PI} \cdot 100
         """
         return ((self.liquid_limit - nmc) / self.plasticity_index) * 100.0
 
 
-class SizeDistribution:
-    """Features obtained from the Particle Size Distribution graph."""
+class _SizeDistribution:
+    """Particle size distribution of soil sample.
+
+    Features obtained from the Particle Size Distribution graph.
+    """
 
     def __init__(self, d_10: float = 0, d_30: float = 0, d_60: float = 0):
-        """
-        :param float d_10: Diameter at which 10% of the soil by weight is finer.
-        :param float d_30: Diameter at which 30% of the soil by weight is finer.
-        :param float d_60: Diameter at which 60% of the soil by weight is finer.
-        """
         self.d_10 = d_10
         self.d_30 = d_30
         self.d_60 = d_60
@@ -256,9 +281,6 @@ class SizeDistribution:
         :param coarse_soil: Coarse fraction of the soil sample. Valid arguments 
                             are ``USCSSymbol.GRAVEL`` and ``USCSSymbol.SAND``.
         """
-        if not (coarse_soil in (USCSSymbol.GRAVEL, USCSSymbol.SAND)):
-            raise NotImplementedError
-
         if coarse_soil is USCSSymbol.GRAVEL:
             if 1 < self.coeff_of_curvature < 3 and self.coeff_of_uniformity >= 4:
                 grade = USCSSymbol.WELL_GRADED
@@ -280,22 +302,31 @@ class PSD:
     """
 
     def __init__(self, fines: float, sand: float,
-                 size_dist: Optional[SizeDistribution] = None):
+                 d_10: float = 0, d_30: float = 0, d_60: float = 0):
         """
-        :param fines: Percentage of fines in soil sample i.e. The percentage of 
-                      soil sample passing through No. 200 sieve (0.075mm).
+        :param fines: Percentage of fines in soil sample (%) i.e. The
+                      percentage of soil sample passing through No. 200 sieve
+                      (0.075mm).
         :type fines: float
 
-        :param sand: Percentage of sand in soil sample.
+        :param sand: Percentage of sand in soil sample (%).
         :type sand: float
 
-        :param size_dist: Particle size distribution of soil sample.
-        :type size_dist: SizeDistribution
+        :param d_10: Diameter at which 10% of the soil by weight is finer.
+        :type d_10: float
+        :param d_30: Diameter at which 30% of the soil by weight is finer.
+        :type d_30: float
+        :param d_60: Diameter at which 60% of the soil by weight is finer.
+        :type d_60: float
         """
         self.fines = fines
         self.sand = sand
-        self.gravel = 100.0 - (fines + sand)
-        self.size_dist = size_dist if size_dist else SizeDistribution()
+        self.size_dist = _SizeDistribution(d_10=d_10, d_30=d_30, d_60=d_60)
+
+    @property
+    def gravel(self):
+        """Percentage of gravel in soil sample (%)."""
+        return 100.0 - (self.fines + self.sand)
 
     @property
     def coarse_material_type(self) -> USCSSymbol:
@@ -309,7 +340,7 @@ class PSD:
     def coeff_of_curvature(self) -> float:
         r"""Coefficient of curvature of soil sample.
 
-        Coefficient of curvature :math:`(C_c)` is given by the formula:
+        :Equation:
 
         .. math:: C_c = \dfrac{D^2_{30}}{D_{60} \cdot D_{10}}
 
@@ -323,13 +354,13 @@ class PSD:
     def coeff_of_uniformity(self) -> float:
         r"""Coefficient of uniformity of soil sample.
 
-        Coefficient of uniformity :math:`(C_u)` is given by the formula:
+        :Equation:
 
         .. math:: C_u = \dfrac{D_{60}}{D_{10}}
 
-        :math:`C_u` value greater than 4 to 6 classifies the soil as well graded
-        for gravels and sands respectively. When :math:`C_u` is less than 4, it
-        is classified as poorly graded or uniformly graded soil.
+        :math:`C_u` value greater than 4 to 6 classifies the soil as well
+        graded for gravels and sands respectively. When :math:`C_u` is less
+        than 4, it is classified as poorly graded or uniformly graded soil.
 
         Higher values of :math:`C_u` indicates that the soil mass consists of
         soil particles with different size ranges.
@@ -346,12 +377,19 @@ class PSD:
 
         Conditions for a well-graded soil:
 
+        :Equation:
+
         - :math:`1 \lt C_c \lt 3` and :math:`C_u \ge 4` (for gravels)
         - :math:`1 \lt C_c \lt 3` and :math:`C_u \ge 6` (for sands)
         """
         return self.size_dist.grade(coarse_soil=self.coarse_material_type)
 
 
+class SoilClf(NamedTuple):
+    symbol: str
+    description: str
+
+
 class AASHTO:
     r"""American Association of State Highway and Transportation Officials
     (AASHTO) classification system.
@@ -373,6 +411,8 @@ class AASHTO:
         The ``GI`` must be mentioned even when it is zero, to indicate that the 
         soil has been classified as per AASHTO system.
 
+    :Equation:
+
     .. math::
 
         GI = (F_{200} - 35)[0.2 + 0.005(LL - 40)] + 0.01(F_{200} - 15)(PI - 10)
@@ -381,11 +421,11 @@ class AASHTO:
     def __init__(self, atterberg_limits: AtterbergLimits,
                  fines: float, add_group_idx=True):
         """
-        :param atterberg_limits: Atterberg limits of the soil.
+        :param atterberg_limits: Atterberg limits of soil sample.
         :type atterberg_limits: AtterbergLimits
 
-        :param fines: Percentage of fines in soil sample i.e. The percentage of 
-                      soil sample passing through No. 200 sieve (0.075mm).
+        :param fines: Percentage of fines in soil sample (%) i.e. The percentage
+                      of soil sample passing through No. 200 sieve (0.075mm).
         :type fines: float
 
         :param add_group_idx: Used to indicate whether the group index should
@@ -425,7 +465,7 @@ class AASHTO:
         """Return the AASHTO classification of the soil."""
         soil_clf = self._classify()
 
-        symbol, description = soil_clf.clf_symbol, soil_clf.clf_description
+        symbol, description = soil_clf.symbol, soil_clf.description
 
         if self.add_group_idx:
             symbol = f"{symbol}({self.group_index():.0f})"
@@ -513,7 +553,7 @@ class USCS:
     termed as Peat. (:math:`P_t`)
     """
 
-    def __init__(self, atterberg_limits: AtterbergLimits, 
+    def __init__(self, atterberg_limits: AtterbergLimits,
                  psd: PSD, organic=False):
         """
         :param atterberg_limits: Atterberg limits of the soil.
@@ -539,13 +579,13 @@ class USCS:
             soil_clf = USCSSymbol[soil_clf]
 
         if isinstance(soil_clf, USCSSymbol):
-            return SoilClf(soil_clf.clf_symbol, soil_clf.clf_description)
+            return SoilClf(soil_clf.symbol, soil_clf.description)
 
         # Handling tuple or list case for dual classification
         first_clf, second_clf = map(lambda clf: USCSSymbol[clf], soil_clf)
 
-        comb_symbol = f"{first_clf.clf_symbol},{second_clf.clf_symbol}"
-        comb_desc = f"{first_clf.clf_description},{second_clf.clf_description}"
+        comb_symbol = f"{first_clf.symbol},{second_clf.symbol}"
+        comb_desc = f"{first_clf.description},{second_clf.description}"
 
         return SoilClf(comb_symbol, comb_desc)
 
@@ -642,40 +682,55 @@ class USCS:
                 f"{coarse_material_type}{fine_material_type}")
 
 
-def create_soil_classifier(liquid_limit: float, plastic_limit: float,
-                           fines: float, sand: Optional[float] = None,
+@enum_repr
+class CLF_TYPE(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,
+                           sand: Optional[float] = None,
                            d_10: float = 0, d_30: float = 0, d_60: float = 0,
-                           add_group_idx: bool = True, organic: bool = False,
-                           clf_type: CLF_TYPE | str | None = None
+                           add_group_idx: bool = True,
+                           organic: bool = False,
+                           clf_type: Optional[CLF_TYPE | str] = None
                            ) -> SoilClassifier:
     """ A factory function that encapsulates the creation of a soil classifier.
 
     :param liquid_limit: Water content beyond which soils flows under their own
-                         weight. It can also be defined as the minimum moisture
-                         content at which a soil flows upon application of a
-                         very small shear force. (%)
+                         weight (%). It can also be defined as the minimum
+                         moisture content at which a soil flows upon application
+                         of a very small shear force.
     :type liquid_limit: float
 
     :param plastic_limit: Water content at which plastic deformation can be
-                          initiated. It is also the minimum water content at
+                          initiated (%). It is also the minimum water content at
                           which soil can be rolled into a thread 3mm thick.
-                          (molded without breaking) (%)
+                          (molded without breaking)
     :type plastic_limit: float
 
-    :param fines: Percentage of fines in soil sample i.e. The percentage of
-                  soil sample passing through No. 200 sieve (0.075mm). (%)
+    :param fines: Percentage of fines in soil sample (%) i.e. The percentage of
+                  soil sample passing through No. 200 sieve (0.075mm).
     :type fines: float
 
-    :param sand: Percentage of sand in soil sample. (%)
+    :param sand: Percentage of sand in soil sample (%).
     :type sand: float
 
-    :param d_10: Diameter at which 10% of the soil by weight is finer. (mm)
+    :param d_10: Diameter at which 10% of the soil by weight is finer.
     :type d_10: float
 
-    :param d_30: Diameter at which 30% of the soil by weight is finer. (mm)
+    :param d_30: Diameter at which 30% of the soil by weight is finer.
     :type d_30: float
 
-    :param d_60: Diameter at which 60% of the soil by weight is finer. (mm)
+    :param d_60: Diameter at which 60% of the soil by weight is finer.
     :type d_60: float
 
     :param add_group_idx: Used to indicate whether the group index should
@@ -683,28 +738,35 @@ def create_soil_classifier(liquid_limit: float, plastic_limit: float,
                           True.
     :type add_group_idx: bool, optional
 
-    :param organic: Indicates whether soil is organic or not, defaults to
-                    False.
+    :param organic: Indicates whether soil is organic or not, defaults to False.
     :type organic: bool, optional
 
     :param clf_type: Used to indicate which type of soil classifier should be
                      used, defaults to None.
-    :type clf_type: ClfType, optional
+    :type clf_type: CLF_TYPE | str
 
-    :raises ValueError: Raises ValueError if ``clf_type`` is ``None`` or
-                        invalid
+    :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)}")
+
     if clf_type is None:
-        raise ValueError("clf_type must be specified")
+        raise ValueError(msg)
 
-    # raises ValueError if clf_type is not supported
-    if isinstance(clf_type, str):
-        clf_type = CLF_TYPE(clf_type.casefold())
+    try:
+        clf_type = CLF_TYPE(str(clf_type).casefold())
+    except ValueError as e:
+        raise ValueError(msg) from e
 
-    al = AtterbergLimits(liquid_limit=liquid_limit, plastic_limit=plastic_limit)
+    atterberg_lmts = AtterbergLimits(liquid_limit=liquid_limit,
+                                     plastic_limit=plastic_limit)
 
     if clf_type == CLF_TYPE.AASHTO:
-        clf = AASHTO(atterberg_limits=al, fines=fines, 
+        clf = AASHTO(atterberg_limits=atterberg_lmts,
+                     fines=fines,
                      add_group_idx=add_group_idx)
         return clf
 
@@ -712,8 +774,7 @@ def create_soil_classifier(liquid_limit: float, plastic_limit: float,
     if sand is None:
         raise ValueError("sand must be specified for USCS classification")
 
-    size_dist = SizeDistribution(d_10=d_10, d_30=d_30, d_60=d_60)
-    psd = PSD(fines=fines, sand=sand, size_dist=size_dist)
-    clf = USCS(atterberg_limits=al, psd=psd, organic=organic)
+    psd = PSD(fines=fines, sand=sand, d_10=d_10, d_30=d_30, d_60=d_60)
+    clf = USCS(atterberg_limits=atterberg_lmts, psd=psd, organic=organic)
 
     return clf