Skip to content

geolysis.soil_classifier

CLASS DESCRIPTION
AtterbergLimits

Represents the water contents at which soil changes from one state

PSD

Quantitative proportions by mass of various sizes of particles

AASHTO

American Association of State Highway and Transportation

USCS

Unified Soil Classification System (USCS).

FUNCTION DESCRIPTION
create_aashto_classifier

A helper function that encapsulates the creation of a AASHTO

create_uscs_classifier

A helper function that encapsulates the creation of a USCS

SizeDistError

Bases: ZeroDivisionError

Exception raised when size distribution is not provided.

USCSSymbol

Bases: _Clf

Unified Soil Classification System (USCS) symbols and descriptions.

Each member represents a USCS soil type, grading, or plasticity symbol. Aliases are provided where applicable.

ATTRIBUTE DESCRIPTION
G

Gravel

S

Sand

M

Silt

C

Clay

O

Organic soil

W

Well graded

P

Poorly graded

L

Low plasticity

H

High plasticity

GW

Well graded gravels

GP

Poorly graded gravels

GM

Silty gravels

GC

Clayey gravels

GM_GC

Gravelly clayey silt

GW_GM

Well graded gravel with silt

GP_GM

Poorly graded gravel with silt

GW_GC

Well graded gravel with clay

GP_GC

Poorly graded gravel with clay

SW

Well graded sands

SP

Poorly graded sands

SM

Silty sands

SC

Clayey sands

SM_SC

Sandy clayey silt

SW_SM

Well graded sand with silt

SP_SM

Poorly graded sand with silt

SW_SC

Well graded sand with clay

SP_SC

Poorly graded sand with clay

ML

Inorganic silts with low plasticity

CL

Inorganic clays with low plasticity

ML_CL

Clayey silt with low plasticity

OL

Organic clays with low plasticity

MH

Inorganic silts with high plasticity

CH

Inorganic clays with high plasticity

OH

Organic silts with high plasticity

Pt

Highly organic soils

G = ('G', 'Gravel') class-attribute instance-attribute

Gravel

S = ('S', 'Sand') class-attribute instance-attribute

Sand

M = ('M', 'Silt') class-attribute instance-attribute

Silt

C = ('C', 'Clay') class-attribute instance-attribute

Clay

O = ('O', 'Organic') class-attribute instance-attribute

Organic soil

W = ('W', 'Well graded') class-attribute instance-attribute

Well graded

P = ('P', 'Poorly graded') class-attribute instance-attribute

Poorly graded

L = ('L', 'Low plasticity') class-attribute instance-attribute

Low plasticity

H = ('H', 'High plasticity') class-attribute instance-attribute

High plasticity

GW = ('GW', 'Well graded gravels') class-attribute instance-attribute

Well graded gravels

GP = ('GP', 'Poorly graded gravels') class-attribute instance-attribute

Poorly graded gravels

GM = ('GM', 'Silty gravels') class-attribute instance-attribute

Silty gravels

GC = ('GC', 'Clayey gravels') class-attribute instance-attribute

Clayey gravels

GM_GC = ('GM-GC', 'Gravelly clayey silt') class-attribute instance-attribute

Gravelly clayey silt

GW_GM = ('GW-GM', 'Well graded gravel with silt') class-attribute instance-attribute

Well graded gravel with silt

GP_GM = ('GP-GM', 'Poorly graded gravel with silt') class-attribute instance-attribute

Poorly graded gravel with silt

GW_GC = ('GW-GC', 'Well graded gravel with clay') class-attribute instance-attribute

Well graded gravel with clay

GP_GC = ('GP-GC', 'Poorly graded gravel with clay') class-attribute instance-attribute

Poorly graded gravel with clay

SW = ('SW', 'Well graded sands') class-attribute instance-attribute

Well graded sands

SP = ('SP', 'Poorly graded sands') class-attribute instance-attribute

Poorly graded sands

SM = ('SM', 'Silty sands') class-attribute instance-attribute

Silty sands

SC = ('SC', 'Clayey sands') class-attribute instance-attribute

Clayey sands

SM_SC = ('SM-SC', 'Sandy clayey silt') class-attribute instance-attribute

Sandy clayey silt

SW_SM = ('SW-SM', 'Well graded sand with silt') class-attribute instance-attribute

Well graded sand with silt

SP_SM = ('SP-SM', 'Poorly graded sand with silt') class-attribute instance-attribute

Poorly graded sand with silt

SW_SC = ('SW-SC', 'Well graded sand with clay') class-attribute instance-attribute

Well graded sand with clay

SP_SC = ('SP-SC', 'Poorly graded sand with clay') class-attribute instance-attribute

Poorly graded sand with clay

ML = ('ML', 'Inorganic silts with low plasticity') class-attribute instance-attribute

Inorganic silts with low plasticity

CL = ('CL', 'Inorganic clays with low plasticity') class-attribute instance-attribute

Inorganic clays with low plasticity

ML_CL = ('ML-CL', 'Clayey silt with low plasticity') class-attribute instance-attribute

Clayey silt with low plasticity

OL = ('OL', 'Organic clays with low plasticity') class-attribute instance-attribute

Organic clays with low plasticity

MH = ('MH', 'Inorganic silts with high plasticity') class-attribute instance-attribute

Inorganic silts with high plasticity

CH = ('CH', 'Inorganic clays with high plasticity') class-attribute instance-attribute

Inorganic clays with high plasticity

OH = ('OH', 'Organic silts with high plasticity') class-attribute instance-attribute

Organic silts with high plasticity

Pt = ('Pt', 'Highly organic soils') class-attribute instance-attribute

Highly organic soils

AASHTOSymbol

Bases: _Clf

AASHTO soil classification symbols and descriptions.

Each member represents a standard AASHTO soil class used in pavement and highway engineering.

ATTRIBUTE DESCRIPTION
A_1_a

Stone fragments, gravel, and sand

A_1_b

Stone fragments, gravel, and sand

A_3

Fine sand

A_2_4

Silty or clayey gravel and sand

A_2_5

Silty or clayey gravel and sand

A_2_6

Silty or clayey gravel and sand

A_2_7

Silty or clayey gravel and sand

A_4

Silty soils

A_5

Silty soils

A_6

Clayey soils

A_7_5

Clayey soils

A_7_6

Clayey soils

A_1_a = ('A-1-a', 'Stone fragments, gravel, and sand') class-attribute instance-attribute

Stone fragments, gravel, and sand

A_1_b = ('A-1-b', 'Stone fragments, gravel, and sand') class-attribute instance-attribute

Stone fragments, gravel, and sand

A_3 = ('A-3', 'Fine sand') class-attribute instance-attribute

Fine sand

A_2_4 = ('A-2-4', 'Silty or clayey gravel and sand') class-attribute instance-attribute

Silty or clayey gravel and sand

A_2_5 = ('A-2-5', 'Silty or clayey gravel and sand') class-attribute instance-attribute

Silty or clayey gravel and sand

A_2_6 = ('A-2-6', 'Silty or clayey gravel and sand') class-attribute instance-attribute

Silty or clayey gravel and sand

A_2_7 = ('A-2-7', 'Silty or clayey gravel and sand') class-attribute instance-attribute

Silty or clayey gravel and sand

A_4 = ('A-4', 'Silty soils') class-attribute instance-attribute

Silty soils

A_5 = ('A-5', 'Silty soils') class-attribute instance-attribute

Silty soils

A_6 = ('A-6', 'Clayey soils') class-attribute instance-attribute

Clayey soils

A_7_5 = ('A-7-5', 'Clayey soils') class-attribute instance-attribute

Clayey soils

A_7_6 = ('A-7-6', 'Clayey soils') class-attribute instance-attribute

Clayey soils

AtterbergLimits(liquid_limit, plastic_limit)

Represents the water contents at which soil changes from one state to the other.

PARAMETER DESCRIPTION
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: float

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: float

METHOD DESCRIPTION
above_A_LINE

Checks if the soil sample is above A-Line.

limit_plot_in_hatched_zone

Checks if soil sample plot in the hatched zone on the

liquidity_index

Return the liquidity index of the soil.

consistency_index

Return the consistency index of the soil.

ATTRIBUTE DESCRIPTION
A_LINE

The A-line determines if a soil is clayey or silty.

liquid_limit

Water content beyond which soils flows under their own weight (%).

TYPE: float

plastic_limit

Water content at which plastic deformation can be initiated (%).

TYPE: float

plasticity_index

Plasticity index (PI) is the range of water content over which

TYPE: float

fine_material_type

Checks whether the soil is either clay or silt.

TYPE: USCSSymbol

A_LINE = __A_LINE() class-attribute instance-attribute

The A-line determines if a soil is clayey or silty.

\(A = 0.73(LL - 20.0)\)

liquid_limit property writable

Water content beyond which soils flows under their own weight (%).

plastic_limit property writable

Water content at which plastic deformation can be initiated (%).

plasticity_index property

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.

\[PI = LL - PL\]

fine_material_type property

Checks whether the soil is either clay or silt.

above_A_LINE()

Checks if the soil sample is above A-Line.

limit_plot_in_hatched_zone()

Checks if soil sample plot in the hatched zone on the atterberg chart.

liquidity_index(nmc)

Return the liquidity index of the soil.

\[I_l = \dfrac{w - PL}{PI} \cdot 100\]

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.

PARAMETER DESCRIPTION
nmc

Moisture contents of the soil in natural condition.

TYPE: float

consistency_index(nmc)

Return the consistency index of the soil.

\[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.

PARAMETER DESCRIPTION
nmc

Moisture contents of the soil in natural condition.

TYPE: float

PSD(fines, sand, d_10=None, d_30=None, d_60=None)

Quantitative proportions by mass of various sizes of particles present in a soil.

PARAMETER DESCRIPTION
fines

Percentage of fines in soil sample (%) i.e. The percentage of soil sample passing through No. 200 sieve (0.075mm).

TYPE: float

sand

Percentage of sand in soil sample (%).

TYPE: float

d_10

Diameter at which 10% of the soil by weight is finer.

TYPE: float | None DEFAULT: None

d_30

Diameter at which 30% of the soil by weight is finer.

TYPE: float | None DEFAULT: None

d_60

Diameter at which 60% of the soil by weight is finer.

TYPE: float | None DEFAULT: None

METHOD DESCRIPTION
has_particle_sizes

Checks if soil sample has particle sizes.

grade

Return the grade of the soil sample, either well graded or

ATTRIBUTE DESCRIPTION
gravel

Percentage of gravel in soil sample (%).

coarse_material_type

Determines whether the soil is either gravel or sand.

TYPE: USCSSymbol

coeff_of_curvature

Coefficient of curvature of soil sample.

TYPE: float

coeff_of_uniformity

Coefficient of uniformity of soil sample.

TYPE: float

gravel property

Percentage of gravel in soil sample (%).

coarse_material_type property

Determines whether the soil is either gravel or sand.

coeff_of_curvature property

Coefficient of curvature of soil sample.

\[C_c = \dfrac{D^2_{30}}{D_{60} \cdot D_{10}}\]

For the soil to be well graded, the value of \(C_c\) must be between 1 and 3.

coeff_of_uniformity property

Coefficient of uniformity of soil sample.

\[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.

Higher values of \(C_u\) indicates that the soil mass consists of soil particles with different size ranges.

has_particle_sizes()

Checks if soil sample has particle sizes.

grade()

Return the grade of the soil sample, either well graded or poorly graded.

Conditions for a well-graded soil:

  • \(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)

AASHTO(atterberg_limits, fines)

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) \(\le\) 35% pass No. 200 sieve
  • A4 ~ A7 (Silt-clay Materials) \(\ge\) 36% pass No. 200 sieve
  • A8 (Organic Materials)

The Group Index (GI) is used to further evaluate soils within a group.

Note

The GI must be mentioned even when it is zero, to indicate that the soil has been classified as per AASHTO system.

\[ GI = (F_{200} - 35)[0.2 + 0.005(LL - 40)] + 0.01(F_{200} - 15)(PI - 10) \]
PARAMETER DESCRIPTION
atterberg_limits

Atterberg limits of soil sample.

TYPE: AtterbergLimits

fines

Percentage of fines in soil sample (%) i.e. The percentage of soil sample passing through No. 200 sieve (0.075mm).

TYPE: float

METHOD DESCRIPTION
group_index

Return the Group Index (GI) of the soil sample.

classify

Return the AASHTO classification of the soil.

ATTRIBUTE DESCRIPTION
fines

Percentage of fines in soil sample (%).

TYPE: float

fines property writable

Percentage of fines in soil sample (%).

group_index()

Return the Group Index (GI) of the soil sample.

classify()

Return the AASHTO classification of the soil.

USCS(atterberg_limits, psd, organic=False)

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.

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.

Highly Organic soils are identified by visual inspection. These soils are termed as Peat (\(P_t\)).

PARAMETER DESCRIPTION
atterberg_limits

Atterberg limits of the soil.

TYPE: AtterbergLimits

psd

Particle size distribution of the soil.

TYPE: PSD

organic

Indicates whether soil is organic or not.

DEFAULT: False

METHOD DESCRIPTION
classify

Return the USCS classification of the soil.

classify()

Return the USCS classification of the soil.

create_aashto_classifier(liquid_limit, plastic_limit, fines)

A helper function that encapsulates the creation of a AASHTO classifier.

PARAMETER DESCRIPTION
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: float

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: float

fines

Percentage of fines in soil sample (%) i.e. The percentage of soil sample passing through No. 200 sieve (0.075mm).

TYPE: float

create_uscs_classifier(liquid_limit, plastic_limit, fines, sand, d_10=None, d_30=None, d_60=None, organic=False)

A helper function that encapsulates the creation of a USCS classifier.

PARAMETER DESCRIPTION
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: float

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: float

fines

Percentage of fines in soil sample (%) i.e. The percentage of soil sample passing through No. 200 sieve (0.075mm).

TYPE: float

sand

Percentage of sand in soil sample (%).

TYPE: float

d_10

Diameter at which 10% of the soil by weight is finer.

TYPE: Optional[float] DEFAULT: None

d_30

Diameter at which 30% of the soil by weight is finer.

TYPE: Optional[float] DEFAULT: None

d_60

Diameter at which 60% of the soil by weight is finer.

TYPE: Optional[float] DEFAULT: None

organic

Indicates whether soil is organic or not.

TYPE: bool DEFAULT: False