Skip to content

Index

subsurfaceio.soil_classification

Soil classification API.

Classify a specimen under USCS, AASHTO, or USDA:

from subsurfaceio.soil_classification import SoilClassification

SoilClassification(model=uscs_inputs).calculate()

Classes:

Name Description
SoilClassification

Soil classification (USCS, AASHTO, USDA).
SoilClassificationAASHTO

AASHTO soil classification inputs.
SoilClassificationResultsAASHTO

AASHTO soil classification results.
SoilClassificationResultsUSCS

USCS soil classification results.
SoilClassificationResultsUSDA

USDA soil classification results.
SoilClassificationResultsUSDAMoreno2018

USDA Moreno soil classification results.
SoilClassificationUSCS

USCS soil classification inputs.
SoilClassificationUSCSGroup

Batch USCS soil classification.
SoilClassificationUSDA

USDA soil classification inputs.
SoilClassificationUSDAMoreno2018

USDA Moreno soil classification inputs.

Attributes:

Name Type Description
DiscriminatedSoilClassificationMethodModel TypeAlias

Method model discriminated on system.
RESULTS
SoilClassificationMethodModel TypeAlias

Undiscriminated union of soil classification method models.

DiscriminatedSoilClassificationMethodModel module-attribute 

DiscriminatedSoilClassificationMethodModel: TypeAlias = (
    Annotated[
        SoilClassificationMethodModel,
        Field(
            discriminator="system",
            description="Soil classification system",
        ),
    ]
)

Method model discriminated on system.

RESULTS module-attribute 

RESULTS = {
    "USCS": SoilClassificationResultsUSCS,
    "AASHTO": SoilClassificationResultsAASHTO,
    "USDA": SoilClassificationResultsUSDA,
    "USDAMoreno2018": SoilClassificationResultsUSDAMoreno2018,
}

SoilClassificationMethodModel module-attribute 

SoilClassificationMethodModel: TypeAlias = (
    SoilClassificationUSCS
    | SoilClassificationAASHTO
    | SoilClassificationUSDA
    | SoilClassificationUSDAMoreno2018
)

Undiscriminated union of soil classification method models.

SoilClassification pydantic-model

Bases: Model

Soil classification (USCS, AASHTO, USDA).

References
  • das2002soil
  • astm2017d2487
  • moreno2018clay
  • astm2015d3282
  • benham2009clarification

Fields:

model pydantic-field 

model: DiscriminatedSoilClassificationMethodModel

results pydantic-field 

results: (
    SoilClassificationResultsUSCS
    | SoilClassificationResultsAASHTO
    | SoilClassificationResultsUSDA
    | SoilClassificationResultsUSDAMoreno2018
    | None
) = None

Calculation results

calculate 

calculate() -> Self

Run the calculation and store results.

Returns:

Type Description
Self

self with results populated.

get_reference_figure 

get_reference_figure() -> plotly.graph_objects.Figure

Overlay this specimen on the published classification chart.

Returns:

Type Description
Figure

Plotted reference figure for the active classification system.

Raises:

Type Description
NotImplementedError

If the method model has no catalog chart.

SoilClassificationAASHTO pydantic-model

Bases: BaseModel

AASHTO soil classification inputs.

Fields:

fines_content pydantic-field 

fines_content: float

function_sequence class-attribute 

function_sequence: FunctionSequence = (
    FunctionSequences.SoilClassificationAASHTO
)

language pydantic-field 

language: Language

liquid_limit pydantic-field 

liquid_limit: NullableFloat = None

non_plastic pydantic-field 

non_plastic: bool = False

percent_passing_no10 pydantic-field 

percent_passing_no10: NullableFloat = None

percent_passing_no40 pydantic-field 

percent_passing_no40: NullableFloat = None

plasticity_index pydantic-field 

plasticity_index: NullableFloat = None

system pydantic-field 

system: Literal['AASHTO']

SoilClassificationResultsAASHTO pydantic-model

Bases: BaseModel

AASHTO soil classification results.

Fields:

aashto_description pydantic-field 

aashto_description: str | None = None

aashto_group_index pydantic-field 

aashto_group_index: int | None = None

aashto_symbol pydantic-field 

aashto_symbol: str | None = None

system pydantic-field 

system: Literal['AASHTO']

SoilClassificationResultsUSCS pydantic-model

Bases: BaseModel

USCS soil classification results.

Fields:

system pydantic-field 

system: Literal['USCS']

uscs_description pydantic-field 

uscs_description: str | None = None

uscs_symbol pydantic-field 

uscs_symbol: str | None = None

SoilClassificationResultsUSDA pydantic-model

Bases: BaseModel

USDA soil classification results.

Fields:

system pydantic-field 

system: Literal['USDA']

usda_description pydantic-field 

usda_description: str | None = None

usda_symbol pydantic-field 

usda_symbol: str | None = None

SoilClassificationResultsUSDAMoreno2018 pydantic-model

Bases: BaseModel

USDA Moreno soil classification results.

Fields:

system pydantic-field 

system: Literal['USDAMoreno2018']

usda_description pydantic-field 

usda_description: str | None = None

usda_symbol pydantic-field 

usda_symbol: str | None = None

SoilClassificationUSCS pydantic-model

Bases: BaseModel

USCS soil classification inputs.

Fields:

curvature_coefficient pydantic-field 

curvature_coefficient: NullableFloat = None

fines_content pydantic-field 

fines_content: float

function_sequence class-attribute 

function_sequence: FunctionSequence = (
    FunctionSequences.SoilClassificationUSCS
)

has_organic_fines pydantic-field 

has_organic_fines: bool = False

language pydantic-field 

language: Language

liquid_limit pydantic-field 

liquid_limit: NullableFloat = None

moreno_alonso_plasticity_modification pydantic-field 

moreno_alonso_plasticity_modification: bool = False

non_plastic pydantic-field 

non_plastic: bool = False

percent_gravel pydantic-field 

percent_gravel: float

percent_sand pydantic-field 

percent_sand: float

plasticity_index pydantic-field 

plasticity_index: NullableFloat = None

system pydantic-field 

system: Literal['USCS']

uniformity_coefficient pydantic-field 

uniformity_coefficient: NullableFloat = None

SoilClassificationUSCSGroup pydantic-model

Bases: Model

Batch USCS soil classification.

References
  • das2002soil
  • astm2017d2487
  • moreno2018clay
  • astm2015d3282
  • benham2009clarification

Fields:

items pydantic-field 

items: list[SoilClassificationUSCS]

results pydantic-field 

results: list[SoilClassificationResultsUSCS] | None = None

calculate 

calculate() -> Self

Run the calculation and store results.

Returns:

Type Description
Self

self with results populated.

SoilClassificationUSDA pydantic-model

Bases: BaseModel

USDA soil classification inputs.

Fields:

function_sequence class-attribute 

function_sequence: FunctionSequence = (
    FunctionSequences.SoilClassificationUSDA
)

language pydantic-field 

language: Language

percent_clay pydantic-field 

percent_clay: float

percent_sand pydantic-field 

percent_sand: float

system pydantic-field 

system: Literal['USDA']

SoilClassificationUSDAMoreno2018 pydantic-model

Bases: BaseModel

USDA Moreno soil classification inputs.

Fields:

function_sequence class-attribute 

function_sequence: FunctionSequence = (
    FunctionSequences.SoilClassificationUSDAMoreno2018
)

language pydantic-field 

language: Language

liquid_limit pydantic-field 

liquid_limit: NullableFloat = None

non_plastic pydantic-field 

non_plastic: bool = False

percent_sand pydantic-field 

percent_sand: float

plasticity_index pydantic-field 

plasticity_index: NullableFloat = None

system pydantic-field 

system: Literal['USDAMoreno2018']