geolysis 0.8.0__py3-none-any.whl → 0.10.0__py3-none-any.whl

geolysis/soil_classifier.py

@@ -1,25 +1,25 @@
-"""This module provides classes for soil classification using systems like 
-USCS and AASHTO, based on particle size distribution and  Atterberg limits.
-"""
 import enum
-from typing import NamedTuple, Optional, Sequence
+from dataclasses import dataclass
+from typing import Annotated, Sequence
 
-from .utils import enum_repr, isclose, round_, validators
-from .utils.exceptions import ErrorMsg, ValidationError
+from func_validator import validate_func_args, MustBeNonNegative
 
-__all__ = ["ClfType",
-           "AtterbergLimits",
-           "PSD",
-           "AASHTO",
-           "USCS",
-           "create_soil_classifier"]
+from .utils import isclose, round_
+
+__all__ = [
+    "AtterbergLimits",
+    "PSD",
+    "AASHTO",
+    "USCS",
+    "create_aashto_classifier",
+    "create_uscs_classifier",
+]
 
 
 class SizeDistError(ZeroDivisionError):
     """Exception raised when size distribution is not provided."""
 
 
-@enum_repr
 class _Clf(tuple, enum.Enum):
 
     def __str__(self) -> str:
@@ -35,63 +35,191 @@ class _Clf(tuple, enum.Enum):
 
 
 class USCSSymbol(_Clf):
-    """Unified Soil Classification System (USCS) symbols and descriptions."""
-    G = GRAVEL = ("G", "Gravel")
-    S = SAND = ("S", "Sand")
-    M = SILT = ("M", "Silt")
-    C = CLAY = ("C", "Clay")
-    O = ORGANIC = ("O", "Organic")
-    W = WELL_GRADED = ("W", "Well graded")
-    P = POORLY_GRADED = ("P", "Poorly graded")
-    L = LOW_PLASTICITY = ("L", "Low plasticity")
-    H = HIGH_PLASTICITY = ("H", "High plasticity")
+    """
+    Unified Soil Classification System (USCS) symbols and descriptions.
+
+    Each member represents a USCS soil type, grading, or plasticity symbol.
+    Aliases are provided where applicable.
+    """
+
+    # General soil types
+    G = ("G", "Gravel")
+    """Gravel"""
+
+    GRAVEL = G
+
+    S = ("S", "Sand")
+    """Sand"""
+
+    SAND = S
+
+    M = ("M", "Silt")
+    """Silt"""
+
+    SILT = M
+
+    C = ("C", "Clay")
+    """Clay"""
+
+    CLAY = C
+
+    O = ("O", "Organic")
+    """Organic soil"""
+
+    ORGANIC = O
+
+    # Grading descriptors
+    W = ("W", "Well graded")
+    """Well graded"""
+
+    WELL_GRADED = W
+
+    P = ("P", "Poorly graded")
+    """Poorly graded"""
+
+    POORLY_GRADED = P
+
+    # Plasticity descriptors
+    L = ("L", "Low plasticity")
+    """Low plasticity"""
+
+    LOW_PLASTICITY = L
+
+    H = ("H", "High plasticity")
+    """High plasticity"""
+
+    HIGH_PLASTICITY = H
+
+    # Gravels
     GW = ("GW", "Well graded gravels")
+    """Well graded gravels"""
+
     GP = ("GP", "Poorly graded gravels")
+    """Poorly graded gravels"""
+
     GM = ("GM", "Silty gravels")
+    """Silty gravels"""
+
     GC = ("GC", "Clayey gravels")
+    """Clayey gravels"""
+
     GM_GC = ("GM-GC", "Gravelly clayey silt")
+    """Gravelly clayey silt"""
+
     GW_GM = ("GW-GM", "Well graded gravel with silt")
+    """Well graded gravel with silt"""
+
     GP_GM = ("GP-GM", "Poorly graded gravel with silt")
+    """Poorly graded gravel with silt"""
+
     GW_GC = ("GW-GC", "Well graded gravel with clay")
+    """Well graded gravel with clay"""
+
     GP_GC = ("GP-GC", "Poorly graded gravel with clay")
+    """Poorly graded gravel with clay"""
+
+    # Sands
     SW = ("SW", "Well graded sands")
+    """Well graded sands"""
+
     SP = ("SP", "Poorly graded sands")
+    """Poorly graded sands"""
+
     SM = ("SM", "Silty sands")
+    """Silty sands"""
+
     SC = ("SC", "Clayey sands")
+    """Clayey sands"""
+
     SM_SC = ("SM-SC", "Sandy clayey silt")
+    """Sandy clayey silt"""
+
     SW_SM = ("SW-SM", "Well graded sand with silt")
+    """Well graded sand with silt"""
+
     SP_SM = ("SP-SM", "Poorly graded sand with silt")
+    """Poorly graded sand with silt"""
+
     SW_SC = ("SW-SC", "Well graded sand with clay")
+    """Well graded sand with clay"""
+
     SP_SC = ("SP-SC", "Poorly graded sand with clay")
+    """Poorly graded sand with clay"""
+
+    # Silts and clays
     ML = ("ML", "Inorganic silts with low plasticity")
+    """Inorganic silts with low plasticity"""
+
     CL = ("CL", "Inorganic clays with low plasticity")
+    """Inorganic clays with low plasticity"""
+
     ML_CL = ("ML-CL", "Clayey silt with low plasticity")
+    """Clayey silt with low plasticity"""
+
     OL = ("OL", "Organic clays with low plasticity")
+    """Organic clays with low plasticity"""
+
     MH = ("MH", "Inorganic silts with high plasticity")
+    """Inorganic silts with high plasticity"""
+
     CH = ("CH", "Inorganic clays with high plasticity")
+    """Inorganic clays with high plasticity"""
+
     OH = ("OH", "Organic silts with high plasticity")
+    """Organic silts with high plasticity"""
+
     Pt = ("Pt", "Highly organic soils")
+    """Highly organic soils"""
 
 
 class AASHTOSymbol(_Clf):
-    """AASHTO soil classification symbols and descriptions."""
+    """
+    AASHTO soil classification symbols and descriptions.
+
+    Each member represents a standard AASHTO soil class used in
+    pavement and highway engineering.
+    """
+
     A_1_a = ("A-1-a", "Stone fragments, gravel, and sand")
+    """Stone fragments, gravel, and sand"""
+
     A_1_b = ("A-1-b", "Stone fragments, gravel, and sand")
+    """Stone fragments, gravel, and sand"""
+
     A_3 = ("A-3", "Fine sand")
+    """Fine sand"""
+
     A_2_4 = ("A-2-4", "Silty or clayey gravel and sand")
+    """Silty or clayey gravel and sand"""
+
     A_2_5 = ("A-2-5", "Silty or clayey gravel and sand")
+    """Silty or clayey gravel and sand"""
+
     A_2_6 = ("A-2-6", "Silty or clayey gravel and sand")
+    """Silty or clayey gravel and sand"""
+
     A_2_7 = ("A-2-7", "Silty or clayey gravel and sand")
+    """Silty or clayey gravel and sand"""
+
     A_4 = ("A-4", "Silty soils")
+    """Silty soils"""
+
     A_5 = ("A-5", "Silty soils")
+    """Silty soils"""
+
     A_6 = ("A-6", "Clayey soils")
+    """Clayey soils"""
+
     A_7_5 = ("A-7-5", "Clayey soils")
+    """Clayey soils"""
+
     A_7_6 = ("A-7-6", "Clayey soils")
+    """Clayey soils"""
 
 
 class AtterbergLimits:
-    """Represents the water contents at which soil changes from one state to 
-    the other.
+    """Represents the water contents at which soil changes from one state
+    to the other.
     """
 
     class __A_LINE:
@@ -99,62 +227,69 @@ class AtterbergLimits:
         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()
+    """The ``A-line`` determines if a soil is clayey or silty.
+    
+    $A = 0.73(LL - 20.0)$
+    """
 
     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.
-        :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)
-        :type 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.
+        :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).
         """
-        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
 
     @property
     def liquid_limit(self) -> float:
-        """Water content beyond which soils flows under their own weight (%)."""
+        """
+        Water content beyond which soils flows under their own weight (%).
+        """
         return self._liquid_limit
 
     @liquid_limit.setter
-    @validators.ge(0.0)
-    def liquid_limit(self, val: float) -> None:
+    @validate_func_args
+    def liquid_limit(self, val: Annotated[float, MustBeNonNegative]):
         self._liquid_limit = val
 
     @property
     def plastic_limit(self) -> float:
-        """Water content at which plastic deformation can be initiated (%)."""
+        """
+        Water content at which plastic deformation can be initiated (%).
+        """
         return self._plastic_limit
 
     @plastic_limit.setter
-    @validators.ge(0.0)
-    def plastic_limit(self, val: float) -> None:
+    @validate_func_args
+    def plastic_limit(self, val: Annotated[float, MustBeNonNegative]):
+        if self.liquid_limit < val:
+            msg = (
+                f"plastic_limit: {val} cannot be greater than "
+                f"liquid_limit: {self.liquid_limit}"
+            )
+            raise ValueError(msg)
+
         self._plastic_limit = val
 
     @property
     @round_(2)
     def plasticity_index(self) -> float:
-        """Plasticity index (PI) is the range of water content over which the
-        soil remains in the plastic state.
+        """Plasticity index (PI) is the range of water content over which
+        the soil remains in the plastic state.
 
         It is also the numerical difference between the liquid limit and
         plastic limit of the soil.
 
-        :Equation:
-
-        .. math:: PI = LL - PL
+        $$PI = LL - PL$$
         """
         return self.liquid_limit - self.plastic_limit
 
@@ -168,8 +303,8 @@ class AtterbergLimits:
         return self.plasticity_index > self.A_LINE
 
     def limit_plot_in_hatched_zone(self) -> bool:
-        """Checks if soil sample plot in the hatched zone on the atterberg
-        chart.
+        """Checks if soil sample plot in the hatched zone on the
+        atterberg chart.
         """
         return 4 <= self.plasticity_index <= 7 and 10 < self.liquid_limit < 30
 
@@ -177,17 +312,16 @@ class AtterbergLimits:
     def liquidity_index(self, nmc: float) -> float:
         r"""Return the liquidity index of the soil.
 
-        Liquidity index of a soil indicates the nearness of its ``natural water
-        content`` to its ``liquid limit``. When the soil is at the plastic
-        limit its liquidity index is zero. Negative values of the liquidity
-        index indicate that the soil is in a hard (desiccated) state. It is
-        also known as Water-Plasticity ratio.
-
-        :param float nmc: Moisture contents of the soil in natural condition.
+        $$I_l = \dfrac{w - PL}{PI} \cdot 100$$
 
-        :Equation:
+        Liquidity index of a soil indicates the nearness of its
+        `natural water content` to its `liquid limit`. When the soil
+        is at the plastic limit its liquidity index is zero. Negative
+        values of the liquidity index indicate that the soil is in a
+        hard (desiccated) state. It is also known as Water-Plasticity
+        ratio.
 
-        .. math:: I_l = \dfrac{w - PL}{PI} \cdot 100
+        :param nmc: Moisture contents of the soil in natural condition.
         """
         return ((nmc - self.plastic_limit) / self.plasticity_index) * 100.0
 
@@ -195,22 +329,21 @@ class AtterbergLimits:
     def consistency_index(self, nmc: float) -> float:
         r"""Return the consistency index of the soil.
 
-        Consistency index indicates the consistency (firmness) of soil. It
-        shows the nearness of the ``natural water content`` of the soil to its
-        ``plastic limit``. When the soil is at the liquid limit, the
-        consistency index is zero. The soil at consistency index of zero will
-        be extremely soft and has negligible shear strength. A soil at a water
-        content equal to the plastic limit has consistency index of 100%
-        indicating that the soil is relatively firm. A consistency index of
-        greater than 100% shows the soil is relatively strong
-        (semi-solid state). A negative value indicate the soil is in the liquid
-        state. It is also known as Relative Consistency.
-
-        :param float nmc: Moisture contents of the soil in natural condition.
-
-        :Equation:
-
-        .. math:: I_c = \dfrac{LL - w}{PI} \cdot 100
+        $$I_c = \dfrac{LL - w}{PI} \cdot 100$$
+
+        Consistency index indicates the consistency (firmness) of soil.
+        It shows the nearness of the ``natural water content`` of the
+        soil to its `plastic limit`. When the soil is at the liquid
+        limit, the consistency index is zero. The soil at consistency
+        index of zero will be extremely soft and has negligible shear
+        strength. A soil at a water content equal to the plastic limit
+        has consistency index of 100% indicating that the soil is
+        relatively firm. A consistency index of greater than 100% shows
+        the soil is relatively strong (semi-solid state). A negative
+        value indicate the soil is in the liquid state. It is also known
+        as Relative Consistency.
+
+        :param nmc: Moisture contents of the soil in natural condition.
         """
         return ((self.liquid_limit - nmc) / self.plasticity_index) * 100.0
 
@@ -221,8 +354,7 @@ class _SizeDistribution:
     Features obtained from the Particle Size Distribution graph.
     """
 
-    def __init__(self, d_10: float = 0.0,
-                 d_30: float = 0.0,
+    def __init__(self, d_10: float = 0.0, d_30: float = 0.0,
                  d_60: float = 0.0):
         self.d_10 = d_10
         self.d_30 = d_30
@@ -240,12 +372,10 @@ class _SizeDistribution:
         return self.d_60 / self.d_10
 
     def grade(self, coarse_soil: USCSSymbol) -> USCSSymbol:
-        """Grade of soil sample. Soil grade can either be well graded or poorly
-        graded.
+        """Grade of soil sample. Soil grade can either be well graded or
+        poorly graded.
 
-        :param coarse_soil: Coarse fraction of the soil sample. Valid arguments 
-                            are :py:enum:mem:`~USCSSymbol.GRAVEL` and
-                            :py:enum:mem:`~USCSSymbol.SAND`.
+        :param coarse_soil: Coarse fraction of the soil sample.
         """
         if coarse_soil is USCSSymbol.GRAVEL:
             if 1 < self.coeff_of_curvature < 3 and self.coeff_of_uniformity >= 4:
@@ -263,27 +393,26 @@ class _SizeDistribution:
 
 
 class PSD:
-    """Quantitative proportions by mass of various sizes of particles present
-    in a soil.
+    """Quantitative proportions by mass of various sizes of particles
+    present in a soil.
     """
 
-    def __init__(self, fines: float, sand: float,
-                 d_10: float = 0, d_30: float = 0, d_60: float = 0):
+    def __init__(
+            self,
+            fines: float,
+            sand: float,
+            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).
-        :type fines: float
-
+                      percentage of soil sample passing through No. 200
+                      sieve (0.075mm).
         :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.
-        :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
@@ -306,11 +435,9 @@ class PSD:
     def coeff_of_curvature(self) -> float:
         r"""Coefficient of curvature of soil sample.
 
-        :Equation:
-
-        .. math:: C_c = \dfrac{D^2_{30}}{D_{60} \cdot D_{10}}
+        $$C_c = \dfrac{D^2_{30}}{D_{60} \cdot D_{10}}$$
 
-        For the soil to be well graded, the value of :math:`C_c` must be
+        For the soil to be well graded, the value of $C_c$ must be
         between 1 and 3.
         """
         return self.size_dist.coeff_of_curvature
@@ -320,15 +447,14 @@ class PSD:
     def coeff_of_uniformity(self) -> float:
         r"""Coefficient of uniformity of soil sample.
 
-        :Equation:
+        $$C_u = \dfrac{D_{60}}{D_{10}}$$
 
-        .. math:: C_u = \dfrac{D_{60}}{D_{10}}
+        $C_u$ value greater than 4 to 6 classifies the soil as well
+        graded for gravels and sands respectively. When $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
+        Higher values of $C_u$ indicates that the soil mass consists of
         soil particles with different size ranges.
         """
         return self.size_dist.coeff_of_uniformity
@@ -338,70 +464,64 @@ class PSD:
         return any(self.size_dist)
 
     def grade(self) -> USCSSymbol:
-        r"""Return the grade of the soil sample, either well graded or poorly
-        graded.
+        r"""Return the grade of the soil sample, either well graded or
+        poorly graded.
 
         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)
+        - $1 \lt C_c \lt 3$ and $C_u \ge 4$ (for gravels)
+        - $1 \lt C_c \lt 3$ and $C_u \ge 6$ (for sands)
         """
         return self.size_dist.grade(coarse_soil=self.coarse_material_type)
 
 
-class SoilClf(NamedTuple):
+@dataclass
+class AASHTOResult:
     symbol: str
+    symbol_no_group_idx: str
     description: str
+    group_index: str
 
 
 class AASHTO:
-    r"""American Association of State Highway and Transportation Officials
-    (AASHTO) classification system.
+    r"""American Association of State Highway and Transportation
+    Officials (AASHTO) classification system.
 
     The AASHTO classification system is useful for classifying soils for
-    highways. It categorizes soils for highways based on particle size analysis
-    and plasticity characteristics. It classifies both coarse-grained and
-    fine-grained soils into eight main groups (A1-A7) with subgroups, along with
-    a separate category (A8) for organic soils.
-
-    - ``A1 ~ A3`` (Granular Materials) :math:`\le` 35% pass No. 200 sieve
-    - ``A4 ~ A7`` (Silt-clay Materials) :math:`\ge` 36% pass No. 200 sieve
-    - ``A8`` (Organic Materials)
+    highways. It categorizes soils for highways based on particle size
+    analysis and plasticity characteristics. It classifies both
+    coarse-grained and fine-grained soils into eight main groups (A1-A7)
+    with subgroups, along with a separate category (A8) for organic
+    soils.
 
-    The Group Index ``(GI)`` is used to further evaluate soils within a group.
+    - `A1 ~ A3` (Granular Materials) $\le$ 35% pass No. 200 sieve
+    - `A4 ~ A7` (Silt-clay Materials) $\ge$ 36% pass No. 200 sieve
+    - `A8` (Organic Materials)
 
-    .. note::
+    The Group Index `(GI)` is used to further evaluate soils within a
+    group.
 
-        The ``GI`` must be mentioned even when it is zero, to indicate that the 
-        soil has been classified as per AASHTO system.
+    !!! note
 
-    :Equation:
+        The `GI` must be mentioned even when it is zero, to indicate
+        that the soil has been classified as per AASHTO system.
 
-    .. math::
 
-        GI = (F_{200} - 35)[0.2 + 0.005(LL - 40)] + 0.01(F_{200} - 15)(PI - 10)
+    $$
+    GI = (F_{200} - 35)[0.2 + 0.005(LL - 40)] + 0.01(F_{200} - 15)(PI - 10)
+    $$
     """
 
-    def __init__(self, atterberg_limits: AtterbergLimits,
-                 fines: float, add_group_idx: bool = True):
+    def __init__(self, atterberg_limits: AtterbergLimits, fines: float):
         """
         :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).
-        :type fines: float
-
-        :param add_group_idx: Used to indicate whether the group index should
-                              be added to the classification or not, defaults
-                              to True.
-        :type add_group_idx: bool, optional
+        :param fines: Percentage of fines in soil sample (%) i.e. The
+                      percentage of soil sample passing through No. 200
+                      sieve (0.075mm).
         """
         self.atterberg_limits = atterberg_limits
         self.fines = fines
-        self.add_group_idx = add_group_idx
 
     @property
     def fines(self) -> float:
@@ -409,35 +529,38 @@ class AASHTO:
         return self._fines
 
     @fines.setter
-    @validators.ge(0.0)
-    def fines(self, val: float) -> None:
+    @validate_func_args
+    def fines(self, val: Annotated[float, MustBeNonNegative]):
         self._fines = val
 
     @round_(ndigits=0)
     def group_index(self) -> float:
         """Return the Group Index (GI) of the soil sample."""
-
         liquid_lmt = self.atterberg_limits.liquid_limit
         plasticity_idx = self.atterberg_limits.plasticity_index
         fines = self.fines
 
-        var_a = 1.0 if (x_0 := fines - 35.0) < 0.0 else min(x_0, 40.0)
-        var_b = 1.0 if (x_0 := liquid_lmt - 40.0) < 0.0 else min(x_0, 20.0)
-        var_c = 1.0 if (x_0 := fines - 15.0) < 0.0 else min(x_0, 40.0)
-        var_d = 1.0 if (x_0 := plasticity_idx - 10.0) < 0.0 else min(x_0, 20.0)
+        x_1 = 1.0 if (x_0 := fines - 35.0) < 0.0 else min(x_0, 40.0)
+        x_2 = 1.0 if (x_0 := liquid_lmt - 40.0) < 0.0 else min(x_0, 20.0)
+        x_3 = 1.0 if (x_0 := fines - 15.0) < 0.0 else min(x_0, 40.0)
+        x_4 = 1.0 if (x_0 := plasticity_idx - 10.0) < 0.0 else min(x_0, 20.0)
 
-        return var_a * (0.2 + 0.005 * var_b) + 0.01 * var_c * var_d
+        return x_1 * (0.2 + 0.005 * x_2) + 0.01 * x_3 * x_4
 
-    def classify(self) -> SoilClf:
+    def classify(self) -> AASHTOResult:
         """Return the AASHTO classification of the soil."""
         soil_clf = self._classify()
 
-        symbol, description = soil_clf.symbol, soil_clf.description
-
-        if self.add_group_idx:
-            symbol = f"{symbol}({self.group_index():.0f})"
+        symbol_no_grp_idx, description = soil_clf.symbol, soil_clf.description
+        group_idx = f"{self.group_index():.0f}"
+        symbol = f"{symbol_no_grp_idx}({group_idx})"
 
-        return SoilClf(symbol, description)
+        return AASHTOResult(
+            symbol=symbol,
+            symbol_no_group_idx=symbol_no_grp_idx,
+            description=description,
+            group_index=group_idx,
+        )
 
     def _classify(self) -> AASHTOSymbol:
         # Silts A4-A7
@@ -498,46 +621,52 @@ class AASHTO:
         return soil_clf
 
 
+@dataclass
+class USCSResult:
+    symbol: str
+    description: str
+
+
 class USCS:
     """Unified Soil Classification System (USCS).
 
-    The Unified Soil Classification System, initially developed by Casagrande
-    in 1948 and later modified in 1952, is widely utilized in engineering
-    projects involving soils. It is the most popular system for soil
-    classification and is similar to Casagrande's Classification System. The
-    system relies on particle size analysis and atterberg limits for
-    classification.
+    The Unified Soil Classification System, initially developed by
+    Casagrande in 1948 and later modified in 1952, is widely utilized in
+    engineering projects involving soils. It is the most popular system
+    for soil classification and is similar to Casagrande's
+    Classification System. The system relies on particle size analysis
+    and atterberg limits for classification.
 
     In this system, soils are first classified into two categories:
 
     - Coarse grained soils: If more than 50% of the soils is retained on
       No. 200 (0.075 mm) sieve, it is designated as coarse-grained soil.
 
-    - Fine grained soils: If more than 50% of the soil passes through No. 200
-      sieve, it is designated as fine-grained soil.
+    - Fine grained soils: If more than 50% of the soil passes through
+      No. 200 sieve, it is designated as fine-grained soil.
 
-    Highly Organic soils are identified by visual inspection. These soils are
-    termed as Peat. (:math:`P_t`)
+    Highly Organic soils are identified by visual inspection. These
+    soils are termed as Peat ($P_t$).
     """
 
-    def __init__(self, atterberg_limits: AtterbergLimits,
-                 psd: PSD, organic=False):
+    def __init__(
+            self,
+            atterberg_limits: AtterbergLimits,
+            psd: PSD,
+            organic=False,
+    ):
         """
         :param atterberg_limits: Atterberg limits of the soil.
-        :type atterberg_limits: AtterbergLimits
 
         :param psd: Particle size distribution of the soil.
-        :type psd: PSD
 
-        :param organic: Indicates whether soil is organic or not, defaults to 
-                        False.
-        :type organic: bool, optional
+        :param organic: Indicates whether soil is organic or not.
         """
         self.atterberg_limits = atterberg_limits
         self.psd = psd
         self.organic = organic
 
-    def classify(self) -> SoilClf:
+    def classify(self):
         """Return the USCS classification of the soil."""
         soil_clf = self._classify()
 
@@ -546,15 +675,17 @@ class USCS:
             soil_clf = USCSSymbol[soil_clf]
 
         if isinstance(soil_clf, USCSSymbol):
-            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.symbol},{second_clf.symbol}"
-        comb_desc = f"{first_clf.description},{second_clf.description}"
+            soil_clf = USCSResult(
+                symbol=soil_clf.symbol, description=soil_clf.description
+            )
+        else:
+            # Handling tuple or list case for dual classification
+            first_clf, second_clf = map(lambda clf: USCSSymbol[clf], soil_clf)
+            comb_symbol = f"{first_clf.symbol},{second_clf.symbol}"
+            comb_desc = f"{first_clf.description},{second_clf.description}"
+            soil_clf = USCSResult(symbol=comb_symbol, description=comb_desc)
 
-        return SoilClf(comb_symbol, comb_desc)
+        return soil_clf
 
     def _classify(self) -> USCSSymbol | str | Sequence[str]:
         # Fine-grained, Run Atterberg
@@ -573,21 +704,17 @@ class USCS:
             # Above A-line and PI > 7
             if self.atterberg_limits.above_A_LINE() and plasticity_idx > 7.0:
                 soil_clf = USCSSymbol.CL
-
             # Limit plot in hatched area on plasticity chart
             elif self.atterberg_limits.limit_plot_in_hatched_zone():
                 soil_clf = USCSSymbol.ML_CL
-
             # Below A-line or PI < 4
             else:
                 soil_clf = USCSSymbol.OL if self.organic else USCSSymbol.ML
-
         # High LL
         else:
             # Above A-Line
             if self.atterberg_limits.above_A_LINE():
                 soil_clf = USCSSymbol.CH
-
             # Below A-Line
             else:
                 soil_clf = USCSSymbol.OH if self.organic else USCSSymbol.MH
@@ -623,11 +750,12 @@ class USCS:
                 soil_clf = self._dual_soil_classifier()
             else:
                 fine_material_type = self.atterberg_limits.fine_material_type
-
-                soil_clf = (f"{coarse_material_type}{USCSSymbol.WELL_GRADED}_"
-                            f"{coarse_material_type}{fine_material_type}",
-                            f"{coarse_material_type}{USCSSymbol.POORLY_GRADED}_"
-                            f"{coarse_material_type}{fine_material_type}")
+                soil_clf = (
+                    f"{coarse_material_type}{USCSSymbol.WELL_GRADED}_"
+                    f"{coarse_material_type}{fine_material_type}",
+                    f"{coarse_material_type}{USCSSymbol.POORLY_GRADED}_"
+                    f"{coarse_material_type}{fine_material_type}",
+                )
 
         # Less than 5% pass No. 200 sieve
         # Obtain Cc and Cu from grain size graph
@@ -636,8 +764,10 @@ class USCS:
                 soil_clf = f"{coarse_material_type}{self.psd.grade()}"
 
             else:
-                soil_clf = (f"{coarse_material_type}{USCSSymbol.WELL_GRADED}",
-                            f"{coarse_material_type}{USCSSymbol.POORLY_GRADED}")
+                soil_clf = (
+                    f"{coarse_material_type}{USCSSymbol.WELL_GRADED}",
+                    f"{coarse_material_type}{USCSSymbol.POORLY_GRADED}",
+                )
 
         return soil_clf
 
@@ -645,104 +775,75 @@ class USCS:
         fine_material_type = self.atterberg_limits.fine_material_type
         coarse_material_type = self.psd.coarse_material_type
 
-        return (f"{coarse_material_type}{self.psd.grade()}_"
-                f"{coarse_material_type}{fine_material_type}")
-
-
-@enum_repr
-class ClfType(enum.StrEnum):
-    """Enumeration of soil classification types."""
-    AASHTO = enum.auto()
-    USCS = enum.auto()
-
+        return (
+            f"{coarse_material_type}{self.psd.grade()}_"
+            f"{coarse_material_type}{fine_material_type}"
+        )
 
-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: Optional[ClfType | str] = None
-                           ) -> AASHTO | USCS:
-    """ 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.
-    :type liquid_limit: float
+def create_aashto_classifier(
+        liquid_limit: float, plastic_limit: float, fines: float
+) -> AASHTO:
+    """A helper function that encapsulates the creation of a AASHTO
+    classifier.
 
-    :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)
-    :type 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.
 
-    :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 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).
 
-    :param sand: Percentage of sand in soil sample (%). This is optional for
-                 :class:`AASHTO` classification.
-    :type sand: float, optional
+    :param fines: Percentage of fines in soil sample (%) i.e. The
+                  percentage of soil sample passing through No. 200
+                  sieve (0.075mm).
+    """
+    atterberg_limits = AtterbergLimits(liquid_limit, plastic_limit)
+    return AASHTO(atterberg_limits, fines)
+
+
+def create_uscs_classifier(
+        liquid_limit: float,
+        plastic_limit: float,
+        fines: float,
+        sand: float,
+        d_10: float = 0,
+        d_30: float = 0,
+        d_60: float = 0,
+        organic: bool = False,
+):
+    """A helper function that encapsulates the creation of a USCS
+    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.
+
+    :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)
+
+    :param fines: Percentage of fines in soil sample (%) i.e. The
+                  percentage of soil sample passing through No. 200
+                  sieve (0.075mm).
+
+    :param sand: Percentage of sand in soil sample (%).
 
     :param d_10: Diameter at which 10% of the soil by weight is finer.
-    :type d_10: float, optional
 
     :param d_30: Diameter at which 30% of the soil by weight is finer.
-    :type d_30: float, optional
 
     :param d_60: Diameter at which 60% of the soil by weight is finer.
-    :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
-                          True.
-    :type add_group_idx: bool, optional
-
-    :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 | 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.
+    :param organic: Indicates whether soil is organic or not.
     """
-    msg = ErrorMsg(param_name="clf_type",
-                   param_value=clf_type,
-                   symbol="in",
-                   param_value_bound=list(ClfType))
-
-    if clf_type is None:
-        raise ValidationError(msg)
-
-    try:
-        clf_type = ClfType(str(clf_type).casefold())
-    except ValueError as e:
-        raise ValidationError(msg) from e
-
-    atterberg_lmts = AtterbergLimits(liquid_limit=liquid_limit,
-                                     plastic_limit=plastic_limit)
-
-    if clf_type == ClfType.AASHTO:
-        clf = AASHTO(atterberg_limits=atterberg_lmts,
-                     fines=fines,
-                     add_group_idx=add_group_idx)
-        return clf
-
-    # USCS classification
-    if not sand:
-        msg = ErrorMsg(param_name="sand",
-                       param_value=sand,
-                       msg="sand must be specified for USCS classification")
-        raise ValidationError(msg)
-
+    atterberg_lmts = AtterbergLimits(liquid_limit, plastic_limit)
     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
+    return USCS(atterberg_limits=atterberg_lmts, psd=psd, organic=organic)